abhigyanpatwari/GitNexus · error

ERR_DLOPEN_FAILED

ERR_DLOPEN_FAILED

Error message

ERR_DLOPEN_FAILED

What it means

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.

Source

Thrown at gitnexus/README.md:455

```

See [#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:

```bash
npm cache clean --force
npx gitnexus@latest analyze
```

### `ERR_DLOPEN_FAILED` / `lbugjs.node` missing (pnpm dlx, pnpx)

GitNexus depends on `@ladybugdb/core`, whose native database 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 put in place and the runtime crashes with `ERR_DLOPEN_FAILED`:

```
Error: dlopen(.../@ladybugdb/core/lbugjs.node, ...): tried: '...' (no such file)
  code: 'ERR_DLOPEN_FAILED'
```

Options that run install scripts:

```bash
# pnpm dlx with explicit build permission (one-off, no global install required)
pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter \
  dlx gitnexus@latest serve

# npm: global install (recommended on npm 11+; bare npx may crash — see section above)
npm install -g gitnexus@latest
gitnexus serve

# npx (npm < 11, or after upgrading npm)
npx gitnexus@latest serve

# pnpm: global install with build scripts allowed (pnpm 10.2+; no approve-builds -g on pnpm 11+)
pnpm add -g --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter gitnexus

View on GitHub (pinned to d540b00184)

Solutions

1. With pnpm: explicitly allow build scripts — `pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest serve`.
2. Prefer a global npm install: `npm install -g gitnexus@latest && gitnexus serve` (recommended on npm 11+).
3. Use `npx gitnexus@latest <cmd>` or `bunx gitnexus@latest <cmd>` which run postinstall by default.
4. If you must use --ignore-scripts, run `node path/to/@ladybugdb/core/scripts/postinstall.js` (or the package's build step) manually afterward.
5. Verify with `node -e "require('@ladybugdb/core')"` from the install dir before running gitnexus.

Example fix

# before (postinstall skipped, addon missing)
pnpm dlx gitnexus@latest analyze
# Error: dlopen(.../@ladybugdb/core/lbugjs.node): no such file (ERR_DLOPEN_FAILED)

# after
pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter \
  dlx gitnexus@latest serve
# or
npm install -g gitnexus@latest && gitnexus analyze

# Validate the addon loads BEFORE running gitnexus:
node -e "try { require('@ladybugdb/core'); console.log('ok'); } catch (e) { console.error(e.code); process.exit(1); }"
# If it prints ERR_DLOPEN_FAILED, the install skipped scripts — reinstall correctly.

function isDlopenMissing(errorOrMessage) {
  const m = typeof errorOrMessage === 'string' ? errorOrMessage : (errorOrMessage?.message ?? '');
  return m.includes('ERR_DLOPEN_FAILED') || m.includes('lbugjs.node');
}

# Shell-level: detect and reinstall in one step
node -e "require('@ladybugdb/core')" 2>/dev/null || \
  npm install -g gitnexus@latest   # triggers postinstall that places lbugjs.node

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

• Failed to install Node.js: {result.get('output', '')}
• Local semantic embeddings are unavailable: the optional embe
• [embed] Failed to delete stale embedding rows — aborting to
• Bridge query prepare failed: ${errMsg}
• Bridge query returned an empty QueryResult array

AI-assisted analysis of abhigyanpatwari/GitNexus@d540b00184 (2026-08-12). Data as JSON: /api/errors/fafedc00c84c48f9. Report an issue: GitHub.