Fix NODE_MODULE_VERSION mismatch in Node.js native modules

What's happening

You just upgraded Node.js or switched branches, and suddenly npm install throws NODE_MODULE_VERSION mismatch. The module you're installing (like bcrypt, sharp, or node-sass) was compiled against a different version of V8 than your current Node runtime. This is infuriating, but it's also a 5-minute problem once you know the order to try things.

Fix 1: Quick rebuild (30 seconds)

Most of the time, the module's prebuilt binary doesn't match your Node version. The simplest solution is to rebuild it from source against your current runtime. This works if you have build tools installed (see below).

1. Close any running Node processes (like your dev server).
2. Run this in your project root:

npm rebuild

If that doesn't do it, force a full rebuild of just the native modules:

npm rebuild --build-from-source

If you're using yarn:

yarn rebuild

This recompiles the module against your current Node version. Wait a minute or two. If the error disappears, you're done. If not, move to Fix 2.

Fix 2: Switch Node versions (5 minutes)

Maybe you're on Node 22 but the module was built for Node 18. Or you're using Electron, which has its own ABI. The real fix is matching your Node version to what the module expects.

If you use nvm (Node Version Manager) on macOS/Linux, check what versions you have:

nvm list

Then switch to the version that matches your project's .nvmrc or package.json engines field:

nvm use 18.20.4

On Windows, use nvm-windows. The command is the same.

After switching, run npm rebuild again. If you're using Electron, skip to Fix 3 because Electron uses its own Node version regardless of what's installed.

Fix 3: Clean install (15+ minutes)

If you're still stuck, it's time to nuke everything. This is the nuclear option that clears stale build artifacts and module caches. I've seen this fix cases where nothing else worked.

3a: Clear npm cache and node_modules

rm -rf node_modules
npm cache clean --force
npm install

On Windows, use rmdir /s node_modules or just delete the folder in Explorer. The cache clean is important because npm sometimes reuses corrupted tarballs.

3b: Reinstall global tools

If you use node-gyp globally (older setups), reinstall it:

npm uninstall -g node-gyp
npm install -g node-gyp

Or use the version that comes with npm—it's usually fine.

3c: Check for build tools

If you still get a compile error during rebuild, you might be missing Python or a C++ compiler. Windows users need Visual Studio Build Tools. macOS users need Xcode Command Line Tools (xcode-select --install). Linux users need build-essential and python3.

3d: Special case: Electron

If you're building an Electron app, the mismatch is between your Electron version and your Node version. The fix is to rebuild against Electron's headers:

npm install --save-dev @electron/rebuild
npx electron-rebuild -f -w your-module-name

Or if you're using electron-rebuild directly:

./node_modules/.bin/electron-rebuild

This recompiles all native modules against the Electron runtime, not your system Node.

Prevention tip

Once you fix it, add a .nvmrc file to your project root with the exact Node version:

18.20.4

That way, your team runs nvm use and gets the same version. No more mystery mismatches.

When to give up and post an issue

If none of these work, the module might be incompatible with your Node version entirely. Check the module's GitHub issues—chances are someone's posted a workaround. Don't waste more than an hour on this; sometimes the real fix is waiting for a module update.