BoundaryML/baml · critical · Error

Cannot find native binding. npm has a bug related to…

Error message

Cannot find native binding. npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). Please try `npm i` again after removing both package-lock.json and node_modules directory.

What it means

native.js tries each platform-specific optional dependency (e.g. @boundaryml/baml-linux-x64-gnu) to load the NAPI .node binding. When every candidate fails or is absent, loadErrors are collected and this error is thrown, pointing at a known npm bug (npm/cli#4828) where optional dependencies are skipped.

Solutions

Delete node_modules and package-lock.json, then run `npm i` again.
Install the platform package explicitly, e.g. `npm i @boundaryml/baml-linux-x64-gnu`.
If on npm, try `npm i --force` or switch to pnpm/yarn which handle optionalDependencies correctly.
Verify your platform/arch/Node ABI is supported; upgrade @boundaryml/baml to a version with a binding for it.

Example fix

// shell, before (broken install)
# npm i
// after
# rm -rf node_modules package-lock.json && npm i

Defensive patterns

Strategy: try-catch

Try / catch

try {
  const baml = require('@boundaryml/baml');
} catch (e) {
  if (String(e.message).startsWith('Cannot find native binding')) {
    console.error('Native binding missing; reinstall with: rm -rf node_modules package-lock.json && npm i');
    process.exit(1);
  }
  throw e;
}

Prevention

Commit a lockfile generated by the package manager you use in CI.
Avoid --no-optional / --omit=optional installs for packages with native bindings.
Pin Node to an LTS version covered by published prebuilds.
After dependency upgrades, do a clean install rather than incremental npm i.

When it happens

Trigger: `require('@boundaryml/baml-linux-x64-gnu')` throws for every platform package; nativeBinding stays falsy and loadErrors is non-empty after the platform file loop.

Common situations: Fresh clone with a package-lock.json generated before the platform packages existed; CI cache missing optional deps; installing with --no-optional; unsupported platform (e.g. musl Alpine without the musl build); Node version outside the binding's supported range.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/b50acebb74738a31. Report an issue: GitHub.

Appendix: source

Thrown at engine/language_client_typescript/native.js:385

  } catch (err) {
    if (process.env.NAPI_RS_FORCE_WASI) {
      loadErrors.push(err)
    }
  }
  if (!nativeBinding) {
    try {
      nativeBinding = require('@boundaryml/baml-wasm32-wasi')
    } catch (err) {
      if (process.env.NAPI_RS_FORCE_WASI) {
        loadErrors.push(err)
      }
    }
  }
}

if (!nativeBinding) {
  if (loadErrors.length > 0) {
    throw new Error(
      `Cannot find native binding. ` +
        `npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). ` +
        'Please try `npm i` again after removing both package-lock.json and node_modules directory.',
      { cause: loadErrors }
    )
  }
  throw new Error(`Failed to load native binding`)
}

module.exports = nativeBinding
module.exports.BamlAudio = nativeBinding.BamlAudio
module.exports.BamlImage = nativeBinding.BamlImage
module.exports.BamlPdf = nativeBinding.BamlPdf
module.exports.BamlRuntime = nativeBinding.BamlRuntime
module.exports.BamlSpan = nativeBinding.BamlSpan
module.exports.BamlVideo = nativeBinding.BamlVideo
module.exports.ClassBuilder = nativeBinding.ClassBuilder
module.exports.ClassPropertyBuilder = nativeBinding.ClassPropertyBuilder

View on GitHub (pinned to bd85ce9dee)