{"record":{"id":"b50acebb74738a31","repo":"BoundaryML/baml","slug":"cannot-find-native-binding-npm-has-a-bug-related-to-optional","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"engine/language_client_typescript/native.js","lineNumber":385,"sourceCode":"  } catch (err) {\n    if (process.env.NAPI_RS_FORCE_WASI) {\n      loadErrors.push(err)\n    }\n  }\n  if (!nativeBinding) {\n    try {\n      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","sourceCodeStart":367,"sourceCodeEnd":403,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_typescript/native.js#L367-L403","documentation":"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.","triggerScenarios":"`require('@boundaryml/baml-linux-x64-gnu')` throws for every platform package; nativeBinding stays falsy and loadErrors is non-empty after the platform file loop.","commonSituations":"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.","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."],"exampleFix":"// shell, before (broken install)\n# npm i\n// after\n# rm -rf node_modules package-lock.json && npm i","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  const baml = require('@boundaryml/baml');\n} catch (e) {\n  if (String(e.message).startsWith('Cannot find native binding')) {\n    console.error('Native binding missing; reinstall with: rm -rf node_modules package-lock.json && npm i');\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["nodejs","native-binding","npm","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"}