Skip to content
Logo

Troubleshooting

No native binding available

The library loads its native binding in the following order:

  1. a local source build (build/Release), present when the addon was compiled on install;
  2. the prebuilt platform package @cartesi/machine-<platform>-<arch> (an optionalDependency of published releases).

If neither is found, loading fails with @cartesi/machine: no native binding available. This usually means the platform has no prebuilt package and the source build was skipped or failed (or install scripts were disabled, e.g. --ignore-scripts). Note the install itself does not fail when no emulator installation is found — it prints a warning and skips the native build, so environments that only need the package's types (documentation builds, monorepo siblings) keep working; the error surfaces when the binding is actually loaded.

To compile from source you need:

  • a C++ compiler and the usual node-gyp toolchain;
  • an installed cartesi-machine emulator 0.21.x distribution, which provides the C API headers and the static libcartesi.a the addon links against: the machine-emulator .deb from the official releases on Debian/Ubuntu, or brew install cartesi/tap/cartesi-machine-emulator on macOS. If installed in a non-standard location, set CARTESI_INC / CARTESI_LIB.

Error spawning server

spawn launches the cartesi-jsonrpc-machine executable. It is resolved in the following order:

  1. the CARTESI_JSONRPC_MACHINE environment variable, if set;
  2. the executable bundled with a source build or with the prebuilt platform package;
  3. cartesi-jsonrpc-machine on the PATH.

If the spawn fails with a "no such file" flavored error, none of the above resolved — set CARTESI_JSONRPC_MACHINE to the full path of the executable, or install the emulator so it is on the PATH.

Also note the server address does not support DNS. So addresses like localhost:0 are not supported, use 127.0.0.1:0 instead.

The WebAssembly module is missing

init() rejects with the WebAssembly module is missing when the module file did not make it next to the code importing it. In a published package it is always there; from a source checkout it is built separately:

pnpm --filter @cartesi/machine build:wasm

That runs the Docker build in wasm/builder.Dockerfile, which compiles libcartesi with Emscripten and links the module, then pnpm build copies it into dist. Pass factory to init to load a copy resolved some other way instead.

A module whose ABI does not match the one the binding expects fails at init() too, with a message naming both versions. That means the module and the TypeScript came from different builds — rebuild the module.

Server calls fail in the browser

forking a machine server, spawning a machine server and their siblings are thrown by the WebAssembly build for everything that needs a process or a socket: spawn, connect, and the server-level methods of RemoteCartesiMachine.

To drive a machine server from a browser, use connectHttp, which reaches the same cartesi-jsonrpc-machine over fetch. To run a machine in the browser, use a local one — rollups accepts it, and rolls back through a snapshot rather than a fork.

The page freezes while a machine runs

run() occupies the thread it is called on, and there is no yield point in it. Move the module into a worker: Worker.

Out of memory in the browser

The WebAssembly heap grows to at most 4GB, and holds the machine's RAM and flash drives, plus anything unpacked into the module's filesystem — a 128MB snapshot written with writeSnapshot occupies 128MB on top of the machine loaded from it.

Delete snapshots from the filesystem (cartesi.fs.unlink) once loaded, and call destroy() on machines you are done with rather than waiting for the garbage collector.