{"record":{"id":"f1f4cea31124c720","repo":"BoundaryML/baml","slug":"failed-to-load-native-binding","errorCode":null,"errorMessage":"Failed to load native binding","messagePattern":"Failed to load native binding","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"engine/language_client_typescript/native.js","lineNumber":392,"sourceCode":"      nativeBinding = require('@boundaryml/baml-wasm32-wasi')\n    } catch (err) {\n      if (process.env.NAPI_RS_FORCE_WASI) {\n        loadErrors.push(err)\n      }\n    }\n  }\n}\n\nif (!nativeBinding) {\n  if (loadErrors.length > 0) {\n    throw new Error(\n      `Cannot find native binding. ` +\n        `npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). ` +\n        'Please try `npm i` again after removing both package-lock.json and node_modules directory.',\n      { cause: loadErrors }\n    )\n  }\n  throw new Error(`Failed to load native binding`)\n}\n\nmodule.exports = nativeBinding\nmodule.exports.BamlAudio = nativeBinding.BamlAudio\nmodule.exports.BamlImage = nativeBinding.BamlImage\nmodule.exports.BamlPdf = nativeBinding.BamlPdf\nmodule.exports.BamlRuntime = nativeBinding.BamlRuntime\nmodule.exports.BamlSpan = nativeBinding.BamlSpan\nmodule.exports.BamlVideo = nativeBinding.BamlVideo\nmodule.exports.ClassBuilder = nativeBinding.ClassBuilder\nmodule.exports.ClassPropertyBuilder = nativeBinding.ClassPropertyBuilder\nmodule.exports.ClientRegistry = nativeBinding.ClientRegistry\nmodule.exports.Collector = nativeBinding.Collector\nmodule.exports.EnumBuilder = nativeBinding.EnumBuilder\nmodule.exports.EnumValueBuilder = nativeBinding.EnumValueBuilder\nmodule.exports.FieldType = nativeBinding.FieldType\nmodule.exports.FunctionLog = nativeBinding.FunctionLog\nmodule.exports.FunctionResult = nativeBinding.FunctionResult","sourceCodeStart":374,"sourceCodeEnd":410,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_typescript/native.js#L374-L410","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Reinstall: `rm -rf node_modules package-lock.json && npm i`.","Check `npm ls @boundaryml/baml` and confirm a platform package like @boundaryml/baml-darwin-arm64 is present under node_modules.","Upgrade @boundaryml/baml to the latest version supporting your platform.","Ensure your bundler/packager does not bundle native .node files; keep the package external in server builds."],"exampleFix":"// webpack.config.js, before\nmodule.exports = { /* default */ };\n// after\nmodule.exports = { externals: { '@boundaryml/baml': 'commonjs @boundaryml/baml' } };","handlingStrategy":"try-catch","validationCode":"try { require('@boundaryml/baml'); } catch { /* binding missing */ }","typeGuard":null,"tryCatchPattern":"try {\n  const baml = require('@boundaryml/baml');\n} catch (e) {\n  if (String(e.message) === 'Failed to load native binding') {\n    console.error('Unsupported platform or missing optional dependency for', process.platform, process.arch);\n  }\n  throw e;\n}","preventionTips":["Verify a matching platform package exists in node_modules (e.g. @boundaryml/baml-linux-x64-gnu).","Keep native packages external in bundler configs.","Test installs in a clean container mirroring your production OS/arch."],"tags":["nodejs","native-binding","napi","installation"],"backgroundTag":"missing-optional-dependency","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}