BoundaryML/baml · critical · Error

Failed to load native binding

Error message

Failed to load native binding

What it means

Fallback throw in native.js: after attempting to require every platform-specific NAPI binding, if no binding loaded and no load errors were recorded, the module gives up with 'Failed to load native binding' and exports nothing.

Solutions

  1. Reinstall: `rm -rf node_modules package-lock.json && npm i`.
  2. Check `npm ls @boundaryml/baml` and confirm a platform package like @boundaryml/baml-darwin-arm64 is present under node_modules.
  3. Upgrade @boundaryml/baml to the latest version supporting your platform.
  4. Ensure your bundler/packager does not bundle native .node files; keep the package external in server builds.

Example fix

// webpack.config.js, before
module.exports = { /* default */ };
// after
module.exports = { externals: { '@boundaryml/baml': 'commonjs @boundaryml/baml' } };
Defensive patterns

Strategy: try-catch

Validate before calling

try { require('@boundaryml/baml'); } catch { /* binding missing */ }

Try / catch

try {
  const baml = require('@boundaryml/baml');
} catch (e) {
  if (String(e.message) === 'Failed to load native binding') {
    console.error('Unsupported platform or missing optional dependency for', process.platform, process.arch);
  }
  throw e;
}

Prevention

When it happens

Trigger: The platform-detection loop in native.js completes without assigning nativeBinding and with an empty loadErrors array — typically no optional dependency matching the current platform is installed at all.

Common situations: Installing on an OS/arch with no published prebuilt binary; package managers or install flags (--omit=optional, yarn bare) stripping optional dependencies; corrupted node_modules; bundlers rewriting require() of the native package.

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/f1f4cea31124c720. Report an issue: GitHub.

Appendix: source

Thrown at engine/language_client_typescript/native.js:392

      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
module.exports.ClientRegistry = nativeBinding.ClientRegistry
module.exports.Collector = nativeBinding.Collector
module.exports.EnumBuilder = nativeBinding.EnumBuilder
module.exports.EnumValueBuilder = nativeBinding.EnumValueBuilder
module.exports.FieldType = nativeBinding.FieldType
module.exports.FunctionLog = nativeBinding.FunctionLog
module.exports.FunctionResult = nativeBinding.FunctionResult

View on GitHub (pinned to bd85ce9dee)