Maaz Zindani

Loading the index…

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

A native Node.js addon fails to load with: Module did not self-register

ErrorUncaught Error: Module did not self-register

Short 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.

  • Applies to Node.js 22, Electron 30+, node-gyp
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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"
  2. 2Match what you see, then jump to its fix

    1. 1It loads with plain node but fails inside the Electron appThe addon was built for Node.js but runs in ElectronFix
    2. 2The 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. 3Module did not self-register, or The specified procedure could not be found, inside Electron on WindowsOn Windows, the module lacks the delay-load hookFix

What does the error look like?

  • Uncaught Error: Module did not self-register
  • The 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 electron

2Fix

Rebuild the native modules against Electron, and repeat it after every npm install.

npm install --save-dev @electron/rebuild
./node_modules/.bin/electron-rebuild

3Verify

Start the app. The module loads without the error.

npx electron .

Confirmed by electronjs.org

Did this fix it?

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.cc

2Fix

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

Did this fix it?

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.gyp

2Fix

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.cmd

Confirmed by electronjs.org

Did this fix it?

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 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.