Node native addon dlopen Fails at Runtime in CI - Fix the ABI Mismatch

A native addon is a compiled .node binary tied to a Node ABI and platform. Loading one built for a different version or OS fails when dlopen runs.

What this error means

A node process throws an Error from process.dlopen, often saying the module was compiled against a different Node.js version, when it loads a native addon.

Error: The module '/home/runner/work/app/app/node_modules/bcrypt/build/Release/bcrypt_lib.node'
was compiled against a different Node.js version using
NODE_MODULE_VERSION 108. This version of Node.js requires
NODE_MODULE_VERSION 115.
    at process.func [as dlopen] (node:internal/modules/cjs/loader:1340:18)

Common causes

A cached addon built for a different Node ABI

node_modules restored from cache contains a .node binary compiled for the Node version that was current when the cache was created.

A platform mismatch between build and run

The addon was built on a different OS or CPU than the runner executes on.

How to fix it

Rebuild the addon on the runner

1. Rebuild native dependencies against the current Node version.
2. Re-run so dlopen loads a matching binary.

- run: npm rebuild

Key the dependency cache on the Node version

1. Include the Node version in the node_modules cache key.
2. Invalidate the cache when Node changes so stale binaries are not reused.

How to prevent it

• Include the Node version and OS in dependency cache keys, rebuild native addons after a Node bump, and avoid sharing a node_modules cache across platforms.

Related guides