Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node.js cannot load a compiled .node addon

ErrorERR_DLOPEN_FAILED

Short answer

ERR_DLOPEN_FAILED means Node.js could not load a compiled .node addon through process.dlopen. The common trigger is a Node.js upgrade after the addon was built: rebuild it with npm rebuild. If the code says ERR_DLOPEN_DISABLED instead, Node.js was started with --no-addons, so remove that flag.

  • Applies to Node.js 22, Node.js 24, npm 10
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Note which Node.js binary is running and whether it was started with extra flags. Then find which package ships the .node file named in the stack trace.

    node -v
    echo "$NODE_OPTIONS"
    npm ls --all 2>/dev/null | head -n 40
  2. 2Match what you see, then jump to its fix

    1. 1Error code ERR_DLOPEN_FAILED, right after switching Node.js versions or restoring an old node_modules folderNode.js was upgraded after the addon was compiledFix
    2. 2Error code ERR_DLOPEN_DISABLEDNode.js is started with --no-addonsFix
    3. 3ERR_DLOPEN_FAILED persists after npm rebuild for one package, or after a major Node.js upgradeThe addon is built on V8 directly and the package has not caught upFix

What does the error look like?

  • ERR_DLOPEN_FAILED
  • ERR_DLOPEN_DISABLED

Cause 1 of 3

Node.js was upgraded after the addon was compiled

1Check

Addons built directly on V8 and Node.js internals may need recompiling when the Node.js major version changes. Compare the version running now with the one you ran npm install under.

node -v
npm ls --all | grep -i -E "sass|sqlite|bcrypt|sharp|canvas" | head

2Fix

Recompile every addon in the project with the Node.js version you run today. Rebuild a single package by naming it.

npm rebuild
# or one package
npm rebuild bcrypt

3Verify

Start the app, or require the package alone.

node -e "require('bcrypt'); console.log('addon loaded')"

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

Node.js is started with --no-addons

1Check

That code is raised only when loading native addons has been turned off with the --no-addons flag. Look for it in the start script, NODE_OPTIONS, a systemd unit or a container command.

grep -rn -e "--no-addons" package.json Dockerfile *.service 2>/dev/null
echo "$NODE_OPTIONS"

2Fix

Remove the flag from every place that starts the process, or replace the native dependency with a pure JavaScript one if you need the flag for hardening.

# before
node --no-addons server.js
# after
node server.js

3Verify

Start the app again; the error code should be gone.

node server.js

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

The addon is built on V8 directly and the package has not caught up

1Check

Node.js supports addons through Node-API, which is stable and is the recommended way to write them; the V8 API can change dramatically between Node.js major releases, so addons using nan or V8 directly may need updating and recompiling. Check the package's own docs for the Node.js versions it supports.

npm view bcrypt engines

2Fix

Update the package to a release that supports your Node.js version, then rebuild.

npm install bcrypt@latest
npm rebuild bcrypt

3Verify

Require the package on its own.

node -e "require('bcrypt'); console.log('addon loaded')"

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Pin the Node.js version in .nvmrc or package.json engines, and use that version in CI and in Docker.
  • Run npm rebuild as a step whenever you switch Node.js versions in a project.
  • Prefer packages built on Node-API when you have a choice.
  • Install dependencies inside the target environment instead of copying node_modules between machines.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.