A native Node.js addon fails to load with: Module did not self-register
Uncaught Error: Module did not self-registerShort answer
A native addon refuses to register when it is loaded in a way it was not built for. Common cases: it was compiled for plain Node.js but runs inside Electron, it is loaded again in a worker thread without being context-aware, or on Windows it lacks the delay-load hook. Rebuild for the right runtime, or use a Node-API addon.
Fix it fast
1Find out which cause you have
Print the path of the .node file named in the error, then check what runs it: plain node, Electron, or a worker thread.
node -p process.version npm ls --all 2>/dev/null | grep -i -E "electron|nw|worker"2Match what you see, then jump to its fix
- 1
It loads with plain node but fails inside the Electron appThe addon was built for Node.js but runs in ElectronFix - 2
The first require works; the error appears when a Worker thread or a second context loads the same .node fileThe addon is loaded more than once, for example in a worker threadFix - 3
Module did not self-register, or The specified procedure could not be found, inside Electron on WindowsOn Windows, the module lacks the delay-load hookFix
- 1
What does the error look like?
Uncaught Error: Module did not self-registerThe specified procedure could not be found
Cause 1 of 3
The addon was built for Node.js but runs in Electron
1Check
Electron uses a different ABI than the standard Node.js binary, so native modules must be recompiled for it. A mismatch shows as a NODE_MODULE_VERSION error that says the module was compiled against a different Node.js version.
npm ls electron2Fix
Rebuild the native modules against Electron, and repeat it after every npm install.
npm install --save-dev @electron/rebuild
./node_modules/.bin/electron-rebuild3Verify
Start the app. The module loads without the error.
npx electron .Confirmed by electronjs.org
Cause 2 of 3
The addon is loaded more than once, for example in a worker thread
1Check
Addons registered with NODE_MODULE() cannot be loaded in multiple contexts or threads at the same time. To load in a main thread and a Worker, an addon must be a Node-API addon or be context-aware.
grep -rn -E "NODE_MODULE\(|NODE_MODULE_INIT|NAPI_MODULE" src/ binding.cc2Fix
If you own the addon, move it to Node-API, which Node.js recommends, or declare it context-aware with NODE_MODULE_INIT(). If it is a third-party package, update it to a release that is Node-API or context-aware.
// addon.cc (Node-API)
#include <node_api.h>
NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
return exports;
}3Verify
Load the addon from the main thread and from a Worker in one run.
node -e "const {Worker}=require('node:worker_threads'); require('./build/Release/addon.node'); new Worker('require(\"./build/Release/addon.node\")',{eval:true}).on('error',console.error)"Confirmed by nodejs.org
Cause 3 of 3
On Windows, the module lacks the delay-load hook
1Check
Electron needs the win_delay_load_hook setting to be true in binding.gyp for node-gyp builds, and it must not be overridden elsewhere.
findstr /n "win_delay_load_hook" binding.gyp2Fix
Set win_delay_load_hook to true in binding.gyp and rebuild for Electron.
{
"targets": [
{
"target_name": "addon",
"win_delay_load_hook": "true"
}
]
}3Verify
Rebuild with electron-rebuild, then start the app.
.\node_modules\.bin\electron-rebuild.cmdConfirmed by electronjs.org
How do I stop it coming back?
- Run electron-rebuild in a postinstall script so a fresh install always rebuilds for Electron.
- Prefer packages that ship Node-API addons: they load in several contexts and stay compatible across Node.js major versions.
- Never copy a build/Release folder between a Node.js project and an Electron project.
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