Skip to content
Calimero JS SDKCalimero JS SDKCalimero JS SDK

Troubleshooting

Build issues

Section titled “Build issues”

QuickJS or WASI SDK not found

Section titled “QuickJS or WASI SDK not found”

The CLI downloads the QuickJS compiler and WASI SDK during its postinstall step. If they’re missing, reinstall to re-trigger the download:

Terminal window
pnpm install   # or: cd node_modules/@calimero-network/calimero-cli-js && pnpm run postinstall

This step needs network access.

Unsupported platform

Section titled “Unsupported platform”

The toolchain publishes binaries for macOS (darwin) and Linux only. On Windows, build inside WSL.

Slow builds

Section titled “Slow builds”

Skip the optimization pass during development:

Terminal window
npx calimero-sdk build src/index.ts --no-optimize

Inspecting the build

Section titled “Inspecting the build”

Add --verbose to see every stage — Rollup bundling, QuickJS compilation, Clang flags, and optimization passes:

Terminal window
npx calimero-sdk build src/index.ts --verbose

Runtime issues

Section titled “Runtime issues”

Method not found

Section titled “Method not found”

A method isn’t exported as a service function. Check that:

  1. It lives on the @Logic-decorated class (not on @State).
  2. It is not the constructor (and not the @Init static method).
  3. The build completed without errors.

Every non-static method on the @Logic class is registered; static methods are not, aside from the @Init initializer.

“ABI manifest is required but not available”

Section titled ““ABI manifest is required but not available””

The embedded ABI is mandatory at runtime. It’s generated automatically during calimero-sdk build — rebuild the service and reinstall the fresh WASM. Don’t hand-edit or strip the bundle.

Event handler not running

Section titled “Event handler not running”

Common causes:

  1. The handler name doesn’t match the string passed to emitWithHandler.
  2. You’re checking the author node — the emitting node does not run its own handler; only receivers do.
  3. The delta carrying the event hasn’t been applied yet (missing parents).

Add logging to confirm what’s emitted:

env.log(`emitting with handler: ${handlerName}`);

Storage errors

Section titled “Storage errors”

Check key/value serialization, that the value isn’t unexpectedly null, and that you’re mutating a rehydrated collection handle rather than a freshly constructed one (see Collections → best practices).

Development issues

Section titled “Development issues”

Cannot find module ‘@calimero-network/calimero-sdk-js’

Section titled “Cannot find module ‘@calimero-network/calimero-sdk-js’”

Install dependencies and build the SDK package before your service:

Terminal window
pnpm install
pnpm build

No hot reload

Section titled “No hot reload”

There is no hot reload. Rebuild after changes; a watch build helps:

Terminal window
pnpm build --watch

WASM size

Section titled “WASM size”

A JS service is roughly ~500 KB (QuickJS runtime + your bundled code + ABI). To keep it small: build with optimization on (the default), remove unused imports, and lean on tree-shaking.

Getting help

Section titled “Getting help”