troubleshooting

<!-- GENERATED from docs/api/troubleshooting.md by scripts/build-agent-skill.mjs. Do not edit. -->

Troubleshooting — common errors and which override to reach for

> When a crossbind build or runtime fails, **don't bypass the system** — almost every common error has a designated override mechanism. This doc lists the errors agents actually hit and routes each to the right override (catalogued in [`overrides.md`](./overrides.md)).

The recovery rule:

1. Read the error literally. 2. Identify which layer it lives in (binding-time / build-time / link-time / runtime / hosting). 3. Reach for the **least invasive** override (target filter → targetSpecs → env → build hooks → extensions). 4. Don't manually edit crossbind source, generated artifacts, or upstream library code outside `replaceList`.

---

Build-time errors

`Error: ENOENT: no such file or directory ... /dist/...`

crossbind expected a `dist/` from a dependency that hasn't been built yet.

• **Cause:** transitive dep wasn't built. pnpm topological order should handle this, but if you ran a single-package build with `pnpm --filter <one>` it skipped the deps.
• **Fix:** `pnpm install && pnpm run build` (full topological), or `pnpm --filter '@crossbind/port-<dep>*' run build` first.

`undefined symbol: <name>` at link

The linker can't find a symbol your code references.

• **Cause A — missing dep:** `dependencies: []` in `crossbind.config.js` doesn't list the package providing this symbol.

**Fix:** add the family dependency and its matching platform-variant dependency in `package.json`. See ADR-0002.

• **Cause B — symbol clash:** two libs export the same symbol. Common with `iconv` (gdal renames it to `libiconv` to avoid clash).

**Fix:** `crossbind.build.js` `replaceList` to rename one set of symbols, or `targetSpecs[].specs.ignoreLibName` to suppress the duplicate.

`error: cannot find -l<libname>`

Linker can't find a library file, but the dep IS declared.

• **Cause:** library was built but produced a different `.a` name than expected. Usually a mismatch between `export.libName` in the dep and what's actually built.
• **Fix:** check `ports/<dep>/<platform>/crossbind.config.js` `export.libName` array; verify the produced `.a` exists in `dist/lib/`.

`wasm-ld: error: --whole-archive ... duplicate symbol`

Two libs define the same function.

• **Fix:** same as "symbol clash" above. `replaceList` rename, or `ignoreLibName` to drop one.

`wasm-ld: error: --shared-memory is disallowed by ... not compiled with 'atomics' or 'bulk-memory' features`

A multithread (`mt`) wasm link pulled in a Rust archive whose objects (std included) were built without the atomics features. Current crossbind cannot produce such an archive — mt Rust builds go through nightly `-Zbuild-std` or fail with install instructions — so the usual source is a **stale cargo-type package prebuilt** built before mt support.

• **Fix:** rebuild the package's wasm prebuilts (`crossbind build -p wasm` in the

package, with `rustup toolchain install nightly --component rust-src` done once) or update to a package version whose mt prebuilt was built that way.

`__wasm__` / `CPL_CPUID` / `__asm__` / SIMD intrinsic compile errors

Upstream library uses CPU-specific code that doesn't compile for Wasm.

• **Fix:** `crossbind.build.js` `replaceList` to gate the intrinsic with `#ifdef __wasm__`. Real example: gdal-wasm.

  replaceList: [{
      regex: /CPL_CPUID\(1, cpuinfo\);/g,
      replacement: '#ifdef __wasm__\ncpuinfo[0]=0;\n#else\nCPL_CPUID(1, cpuinfo);\n#endif',
      paths: ['port/cpl_cpu_features.cpp'],
  }]

`configure: error: cannot find ...` (autotools project)

`buildType: 'configure'` but the configure script can't find a dep header / lib.

• **Fix A:** add the missing dep to `dependencies`. Re-derive `depPaths.X.header` in `getBuildParams`.
• **Fix B:** if your dep IS there, `getBuildParams` may need explicit `--with-X=...=${depPaths.X.header}` flags. Verify the dep name in `depPaths` matches the package short name.

`RuntimeError: index out of bounds` during build

Emscripten itself ran out of memory during compilation.

• **Cause:** linker working set exceeded default heap.
• **Fix:** rare; usually fixed in newer Emscripten. If hitting it: `targetSpecs[].specs.binary.emccFlags: ['-sINITIAL_MEMORY=512MB']`.

iOS: `pipe2 was misdetected as available`

curl-ios SDK 26+ specific.

• **Cause:** autoconf cache miss between SDK detection and actual symbol availability.
• **Fix:** `getBuildParams` adds `'-D_CURL_PREFILL=ON'`. See curl-ios's crossbind.build.js for the prefill cache pattern.

iOS: code signing fails on a build utility

Upstream lib has a tool / utility that's built and signed, but you don't have a dev cert.

• **Fix:** return `'-DCMAKE_XCODE_ATTRIBUTE_CODE_SIGNING_ALLOWED=NO'` and `'-DCMAKE_XCODE_ATTRIBUTE_CODE_SIGNING_REQUIRED=NO'` from the recipe's `getBuildParams` for iOS targets. Real example: `ports/jpegturbo/base/build.mjs`, for libjpeg-turbo's SIMD coverage tool.

---

Binding-time errors

`binding ... silently produces null` or `function returns undefined`

Your C++ function violated a binding rule. See [`cpp-binding-rules.md`](./cpp-binding-rules.md).

• Returning `unique_ptr` instead of `shared_ptr`? Switch.
• Returning a raw pointer (`MyClass*`)? A class the bridge knows comes back as an instance; anything else is a `NativePointer` handle you read with the pointer helpers.
• Using multiple inheritance? Refactor to composition.
• Template not explicitly instantiated? Add `template class X<int>;`.
• Definition only in `.cpp`, not in `.h`? Move definition (or at least public surface) into the header.

SWIG generation failures (`%feature` errors, `Unable to find ...`)

Auto-generated `.i` doesn't fit. Write a manual one — see [`swig-escape.md`](./swig-escape.md).

`Error: Tried to call ... but the function is not exposed`

Function not in the public binding surface.

• **C