[Bug]: better-sqlite3 NODE_MODULE_VERSION mismatch with concurrent sessions using different Node versions (mise/asdf)

[husniadil]

Platform

Claude Code

context-mode version

1.0.25

Doctor output

Server test: PASS
PreToolUse hook: PASS
SessionStart hook: PASS
Hook script exists: PASS
Plugin enabled: PASS
FTS5 / better-sqlite3: PASS (from Node 24 session)
FTS5 / better-sqlite3: FAIL (from Node 20 session — same machine, concurrent)

Prompt that triggered the bug

Starting Claude Code from two different projects — one with Node 24 (via mise .tool-versions), another with Node 20 (global default). The session started second gets NODE_MODULE_VERSION mismatch.

What happened?

When using mise with different Node versions per project, concurrent Claude Code sessions cause NODE_MODULE_VERSION mismatch on better-sqlite3. The plugin cache has a single native binary, but each session resolves a different Node ABI version.

• Node 24.11.0 = ABI 137
• Node 20.19.4 = ABI 115

Whichever session starts first (or last rebuild) "wins". The other session gets:

The module '.../better_sqlite3.node' was compiled against a different
Node.js version using NODE_MODULE_VERSION 137. This version of Node.js
requires NODE_MODULE_VERSION 115.

v1.0.25's auto-rebuild on upgrade helps for single-session usage but doesn't solve concurrent cross-version sessions.

Expected behavior

context-mode should work across concurrent sessions regardless of which Node version each session uses.

Steps to reproduce

1. Install mise with Node 20.x and Node 24.x
2. Project A: .tool-versions with node 24.x
3. Project B: uses global Node 20.x (or its own .tool-versions)
4. Launch Claude Code in Project A → context-mode works
5. Launch Claude Code in Project B concurrently → FTS5/better-sqlite3 FAIL

Setup details

• MCP server registered
• Hooks configured (PreToolUse, PostToolUse, SessionStart, etc.)
• Routing instruction file present (CLAUDE.md / GEMINI.md / AGENTS.md / copilot-instructions.md)

Debug logs

Error: The module '/Users/xxx/.claude/plugins/cache/context-mode/context-mode/1.0.20/node_modules/better-sqlite3/build/Release/better_sqlite3.node'
was compiled against a different Node.js version using
NODE_MODULE_VERSION 137. This version of Node.js requires
NODE_MODULE_VERSION 115. Please try re-compiling or re-installing
the module (for instance, using `npm rebuild` or `npm install`).

Operating System

macOS

JS Runtime

Node 20.19.4 + Node 24.11.0 (via mise, concurrent sessions)

[mksglu]

Fix pushed to next branch: c890da9

What changed

start.mjs now caches per-ABI native binaries side-by-side before loading the server:

node_modules/better-sqlite3/build/Release/
  better_sqlite3.node          ← active binary
  better_sqlite3.abi115.node   ← cached for Node 20
  better_sqlite3.abi137.node   ← cached for Node 24

Startup flow:

1. Check if better_sqlite3.abi{currentABI}.node exists → swap it in (~10ms)
2. If not cached, probe the current binary → if compatible, cache it
3. If ABI mismatch → npm rebuild better-sqlite3 → cache result

First encounter of a new ABI triggers a one-time rebuild (~5-10s). After that, switching between Node versions is instant.

Concurrent session safety: On Unix, replacing the .node file on disk is safe for already-running sessions — the old inode stays open in memory.

How to test

# Pull next branch
git checkout next && git pull

# Session 1: Node 20
mise use node@20
node start.mjs  # creates better_sqlite3.abi115.node

# Session 2 (concurrent): Node 24
mise use node@24
node start.mjs  # detects mismatch → rebuilds → creates abi137.node

# Session 3: back to Node 20
mise use node@20
node start.mjs  # instant — uses cached abi115.node

Will be included in the next release. Let us know if this resolves your setup — happy to iterate.

[thoroc]

Similar setup (I am using mise). And I am getting similar error about better_sqlite3:

  ⎿  Error: Batch execution error: The module
     '/Users/<user>/.config/claude/plugins/cache/context-mode/context-mode/1.0.25/node_modules/better-sqlite3/build/Release/better_sqlite3.node'
     was compiled against a different Node.js version using
     NODE_MODULE_VERSION 115. This version of Node.js requires
     NODE_MODULE_VERSION 137. Please try re-compiling or re-installing
     the module (for instance, using `npm rebuild` or `npm install`).

I have gone through the /context-mode:ctx-upgrade but somehow it is still referencing the 1.0.25 version instead of the latest (at the time of writing) 1.0.51.

Maybe it was due to be on a version that was before the changes were made to fix this upgrade?

I had to remove the cachec version 1.0.25 and then do an install of the plugin to fix this.

[husniadil]

Hey @mksglu — I ran into a follow-up issue with the ABI caching from your fix here.

The cached binary was being trusted based on filename alone (abi137.node), but in my case it contained a binary compiled for ABI 115 (Node 20) that got incorrectly cached under the 137 label. This caused persistent FTS5 failures across session restarts since ensureNativeCompat kept swapping in the bad cache.

I also found that the in-process require() probe can't actually catch this because: (a) dlopen caches native modules at the process level, and (b) require('better-sqlite3') only loads the JS wrapper — the native binary isn't loaded until new Database() is called.

Opened #238 with a fix: child-process probe that instantiates a Database to trigger actual dlopen, plus 6 test cases. Would appreciate your review when you get a chance! 🙏

@thoroc this should also fix the issue you reported above.