Troubleshooting
Most failures have a standard fix that does not touch generated files. Read the error, find its layer (build, link, binding, runtime or hosting) and apply the smallest fix that layer offers.
Build errors
ENOENT: no such file or directory … /dist/…
A dependency is not built yet. Build the whole graph (npm install && npm run build), or that dependency first: a filtered build of one package skips its dependencies.
undefined symbol: <name>
- A missing dependency. The package providing the symbol is not in
dependencies: add it to bothcrossbind.config.jsandpackage.json. - A symbol clash. Two libraries export the same name (classically
iconv). Rename one set with areplaceListentry incrossbind.build.js, or drop the duplicate archive withtargetSpecs[].specs.ignoreLibName.
cannot find -l<libname>
The dependency built, but produced a different .a name than expected. Check export.libName in that package and confirm the file exists under its dist/.../lib/.
CPU intrinsics that will not compile
Upstream code using __asm__, CPL_CPUID or <immintrin.h> has no wasm equivalent. Gate it behind #ifdef __wasm__ through a replaceList entry:
shared-memory is disallowed … not compiled with atomics
A multithreaded link pulled in a Rust archive built without atomics, almost always an old prebuilt of a Rust package. Rebuild that package's wasm output (after rustup toolchain install nightly --component rust-src), or update to a version whose mt prebuilt has them.
RuntimeError: index out of bounds during the build
Emscripten itself ran out of memory while linking. Raise it with targetSpecs[].specs.binary.emccFlags: ['-sINITIAL_MEMORY=512MB'].
Binding errors
A function silently returns null or undefined
The C++ broke one of the binding rules. In order of likelihood:
- Returning
unique_ptrinstead ofshared_ptr. - Multiple inheritance in the bound class.
- A template with no explicit instantiation.
- The definition lives only in the
.cpp; the public surface has to be in the header.
Tried to call … but the function is not exposed
The function is not on the public binding surface: an anonymous namespace, a file-scope static, or a declaration and definition that disagree on static/inline.
Runtime errors
crossOriginIsolated is false,SharedArrayBuffer is not defined- A multithreaded build on a host that does not send the isolation headers. Add COOP/COEP; see Threads and workers.
OPFS is only available inside a Worker scope- Mounting
/opfs/...on the page thread. UseinitNative({ useWorker: true }). OPFS is disabled. Enable fs.opfs in config- OPFS is off: the default in
stbuilds, orfs: { opfs: false }. Turn it on withfs: { opfs: true }, or write under/memfs/.... RuntimeError: out of memory- The wasm heap hit its ceiling. Raise
-sINITIAL_MEMORYor-sMAXIMUM_MEMORY, or stream the input instead of holding it all. Memory grows by default, so this usually means the design holds too much at once. m.someFunc is undefined- A binding rule is broken, or the call came before
initNative()resolved. Check the rules first, then the order. instance.method is not a function- In worker mode, construction returned a promise. Write
const c = await new X(...), and setdts: 'promise'.
Calls hang forever with useWorker: true
Either the worker never started (check the Network tab for the worker script), or the C++ in it is stuck in a loop (the Sources tab shows the worker).
Cross-cutting symptoms
- The streaming compile fails.
wasm streaming compile failedmeans either the host serves.wasmasapplication/octet-streaminstead ofapplication/wasm, ormtandstbuilds got mixed: clean and rebuild after switching. - The build succeeds but produces nothing. Look for
Skipping target: ...in the log: afunctions.isEnabledoverride or atarget.platformfilter is excluding everything. - Hot reload ignores a C++ change. Restart the dev server, then check where
paths.nativepoints: the plugins watch exactly those files.
When nothing above matches
- Check the prerequisites: most odd build failures are a missing tool.
- Rerun the
crossbindcommand withDEBUG=1: a failure prints its full error, stack and cause chain, which usually names the failing step. - Reduce to the smallest reproducer: a fresh project with only the failing dependency.
- Search the error text in the source - error messages are unique enough to find where they are thrown.
- File an issue when the error comes from the toolchain itself rather than from your configuration or the upstream library.