{"record":{"id":"fafedc00c84c48f9","repo":"abhigyanpatwari/GitNexus","slug":"err-dlopen-failed","errorCode":"ERR_DLOPEN_FAILED","errorMessage":"ERR_DLOPEN_FAILED","messagePattern":"ERR_DLOPEN_FAILED","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"gitnexus/README.md","lineNumber":455,"sourceCode":"```\n\nSee [#1939](https://github.com/abhigyanpatwari/GitNexus/issues/1939) and the original [#819](https://github.com/abhigyanpatwari/GitNexus/issues/819) thread. An older variant of this crash (tree-sitter-dart tarball URL) was fixed in gitnexus v1.6.2+ ([#820](https://github.com/abhigyanpatwari/GitNexus/pull/820)); if you still see install failures after upgrading, clear cache:\n\n```bash\nnpm cache clean --force\nnpx gitnexus@latest analyze\n```\n\n### `ERR_DLOPEN_FAILED` / `lbugjs.node` missing (pnpm dlx, pnpx)\n\nGitNexus depends on `@ladybugdb/core`, whose native database addon\n(`lbugjs.node`) is placed by a postinstall script. `pnpm dlx`, `pnpx`, and any\ninstall run with `--ignore-scripts` skip lifecycle scripts, so the addon is\nnever put in place and the runtime crashes with `ERR_DLOPEN_FAILED`:\n\n```\nError: dlopen(.../@ladybugdb/core/lbugjs.node, ...): tried: '...' (no such file)\n  code: 'ERR_DLOPEN_FAILED'\n```\n\nOptions that run install scripts:\n\n```bash\n# pnpm dlx with explicit build permission (one-off, no global install required)\npnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter \\\n  dlx gitnexus@latest serve\n\n# npm: global install (recommended on npm 11+; bare npx may crash — see section above)\nnpm install -g gitnexus@latest\ngitnexus serve\n\n# npx (npm < 11, or after upgrading npm)\nnpx gitnexus@latest serve\n\n# pnpm: global install with build scripts allowed (pnpm 10.2+; no approve-builds -g on pnpm 11+)\npnpm add -g --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter gitnexus","sourceCodeStart":437,"sourceCodeEnd":473,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/README.md#L437-L473","documentation":"Documented in gitnexus/README.md: GitNexus depends on @ladybugdb/core, whose native addon lbugjs.node is placed by a postinstall script. pnpm dlx, pnpx, and any install run with --ignore-scripts skip lifecycle scripts, so the addon is never materialized; the first DB operation then crashes with Node's ERR_DLOPEN_FAILED because dlopen() cannot find the .node file.","triggerScenarios":"Running `pnpm dlx gitnexus@latest analyze`, `pnpx gitnexus@latest serve`, or `npm install --ignore-scripts gitnexus` and then invoking any command that opens the LadybugDB database. The runtime tries to dlopen .../@ladybugdb/core/lbugjs.node and reports 'no such file'.","commonSituations":"pnpm dlx / pnpx by default block install scripts; CI pinning --ignore-scripts for safety; corporate npm config with ignore-scripts=true; npm 11 npx regressions interacting with the addon build.","solutions":["With pnpm: explicitly allow build scripts — `pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest serve`.","Prefer a global npm install: `npm install -g gitnexus@latest && gitnexus serve` (recommended on npm 11+).","Use `npx gitnexus@latest <cmd>` or `bunx gitnexus@latest <cmd>` which run postinstall by default.","If you must use --ignore-scripts, run `node path/to/@ladybugdb/core/scripts/postinstall.js` (or the package's build step) manually afterward.","Verify with `node -e \"require('@ladybugdb/core')\"` from the install dir before running gitnexus."],"exampleFix":"# before (postinstall skipped, addon missing)\npnpm dlx gitnexus@latest analyze\n# Error: dlopen(.../@ladybugdb/core/lbugjs.node): no such file (ERR_DLOPEN_FAILED)\n\n# after\npnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter \\\n  dlx gitnexus@latest serve\n# or\nnpm install -g gitnexus@latest && gitnexus analyze","handlingStrategy":"validation","validationCode":"# Validate the addon loads BEFORE running gitnexus:\nnode -e \"try { require('@ladybugdb/core'); console.log('ok'); } catch (e) { console.error(e.code); process.exit(1); }\"\n# If it prints ERR_DLOPEN_FAILED, the install skipped scripts — reinstall correctly.","typeGuard":"function isDlopenMissing(errorOrMessage) {\n  const m = typeof errorOrMessage === 'string' ? errorOrMessage : (errorOrMessage?.message ?? '');\n  return m.includes('ERR_DLOPEN_FAILED') || m.includes('lbugjs.node');\n}","tryCatchPattern":"# Shell-level: detect and reinstall in one step\nnode -e \"require('@ladybugdb/core')\" 2>/dev/null || \\\n  npm install -g gitnexus@latest   # triggers postinstall that places lbugjs.node","preventionTips":["Avoid pnpm dlx/pnpx for tools with native addons; prefer npm install -g or npx/bunx.","If pnpm is mandatory, pass --allow-build for every package with a native addon.","Never install with --ignore-scripts for packages that ship native addons."],"tags":["native-addon","install","ladybugdb","node","pnpm","documentation"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}