Node.js cannot load a compiled .node addon
ERR_DLOPEN_FAILEDShort 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.
Fix it fast
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 402Match what you see, then jump to its fix
- 1
Error 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
Error code ERR_DLOPEN_DISABLEDNode.js is started with --no-addonsFix - 3
ERR_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
- 1
What does the error look like?
ERR_DLOPEN_FAILEDERR_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" | head2Fix
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 bcrypt3Verify
Start the app, or require the package alone.
node -e "require('bcrypt'); console.log('addon loaded')"Confirmed by docs.npmjs.com
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.js3Verify
Start the app again; the error code should be gone.
node server.jsConfirmed by nodejs.org
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 engines2Fix
Update the package to a release that supports your Node.js version, then rebuild.
npm install bcrypt@latest
npm rebuild bcrypt3Verify
Require the package on its own.
node -e "require('bcrypt'); console.log('addon loaded')"Confirmed by nodejs.org
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 fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack 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 fixBack end
Angular build says it cannot resolve '@angular/localize/init'
Can't resolve '@angular/localize/init' in '/usr/src/app/src'
The build imports @angular/localize, and that package is not in node_modules.
2 causes, each with a fixBack end
The command npm run build -- --prod exited with code 1 (Angular)
The command "npm run build -- --prod" exited with code 1
Exit code 1 only says the build failed; the real message is above it.
2 causes, each with a fix