Node.js ERR_DLOPEN_FAILED - Fix Native Addon (.node) Load Failure in CI

ERR_DLOPEN_FAILED means Node tried to load a compiled .node addon and the OS dynamic loader rejected it. The binary exists, but it was built for a different OS, CPU architecture, libc, or Node ABI than the one running it.

What this error means

Requiring a package with a native addon throws ERR_DLOPEN_FAILED with a detail like "invalid ELF header", "wrong ELF class", or a NODE_MODULE_VERSION mismatch. It commonly appears after copying node_modules from a host into a Linux container, or running a build on a different arch (arm64 vs x64) than it installed on.

Node output

Error [ERR_DLOPEN_FAILED]: /app/node_modules/some-native/build/Release/addon.node:
invalid ELF header
# or:
The module was compiled against a different Node.js version using
NODE_MODULE_VERSION 108. This version requires NODE_MODULE_VERSION 115.
    code: 'ERR_DLOPEN_FAILED'

Common causes

The addon was built for a different OS/arch

A .node compiled on macOS or x64 fails to load on a Linux/arm64 runner. "invalid ELF header" / "wrong ELF class" is the loader rejecting an incompatible binary.

A Node ABI (NODE_MODULE_VERSION) mismatch

The addon was compiled against a different Node major. Each Node major has its own NODE_MODULE_VERSION; a prebuilt or cached addon from another major will not load.

Copied node_modules across environments

Copying node_modules from a host/dev machine into the CI/Docker environment carries platform-specific binaries that do not match the target.

How to fix it

Rebuild native modules in the target environment

Install or rebuild on the same OS/arch/Node that will run the code.

Terminal

rm -rf node_modules
npm ci          # installs/builds for THIS platform
# or rebuild against the current Node ABI:
npm rebuild

Match the platform to available prebuilds

Use a base image whose OS/libc (glibc vs musl) and arch the package publishes prebuilds for.
Pin a Node major the addon supports so its NODE_MODULE_VERSION matches.
Cache native node_modules per platform key, not shared across architectures.

How to prevent it

Build native addons in the same environment that runs them.
Key caches on OS + arch + Node major.
Avoid copying node_modules between platforms.