# 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 `@deroll/cm-<platform>-<arch>` (an `optionalDependency` of published releases).

If neither is found, loading fails with `@deroll/cm: 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.20.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](https://github.com/cartesi/machine-emulator/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](/cm/api/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](https://github.com/cartesi/machine-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.
