Repository navigation
[Bug] better-sqlite3 native module ABI mismatch breaks plugin on Node 25 #1734
Description
Bug Description
The memos-local-openclaw-plugin fails to load after OpenClaw or the plugin itself is updated, throwing:
Error: The module '/path/to/memos-local-openclaw-plugin/node_modules/better-sqlite3/build/Release/better_sqlite3.node'
was compiled against a different Node.js version using NODE_MODULE_VERSION 141.
This version of Node.js requires NODE_MODULE_VERSION 127.
Please try re-compiling or re-installing the module.
This happens because better-sqlite3 is a native C++ addon compiled at install time against the Node ABI of the npm installation environment, but the OpenClaw Gateway may run under a different Node.js version.
Environment
- Plugin: @memtensor/memos-local-openclaw-plugin v1.0.8–1.0.10
- better-sqlite3: ^12.6.3
- macOS (Darwin arm64)
- Node.js version that compiles the module (e.g., v22.x via npm)
- OpenClaw Gateway runtime: Node 25.9.0 (Homebrew Cellar)
Root Cause
- The plugin uses
better-sqlite3, a native C++ module that must be compiled against the exact Node.js ABI version used at runtime postinstall.cjsdetects the mismatch and runsnpm rebuild better-sqlite3, but:- The rebuild uses the npm / Node environment available in the postinstall script context, which may differ from the Gateway runtime's Node version
- The LaunchAgent that runs the OpenClaw Gateway has its own
PATHand may invoke a different Node binary than whatnpm rebuilduses
- Even after a successful rebuild, the mismatch can recur if OpenClaw updates its Node runtime or if the plugin is reinstalled
Steps to Reproduce
- Install/update the plugin (npm install or OpenClaw plugin update)
- Start the OpenClaw Gateway via LaunchAgent
- Plugin registration fails with the ABI mismatch error
- Manual
npm rebuild better-sqlite3in the plugin dir may temporarily fix it, but the problem recurs
Suggested Fixes
Option A — In-process ABI check + rebuild (recommended)
Instead of relying on postinstall, the plugin should detect the ABI mismatch at runtime (in register() or service.start()) using process.versions.modules and validateNativeBinding(). If mismatched, run npm rebuild better-sqlite3 programmatically in a subprocess using the same Node binary that the Gateway is currently using (not whatever npm resolves on PATH):
// In plugin register/startup:
const currentNodeBinary = process.execPath; // Use THIS Node, not npm rebuild env
const { spawnSync } = require('child_process');
spawnSync(currentNodeBinary, ['npm', 'rebuild', 'better-sqlite3'], {
cwd: pluginDir,
stdio: 'pipe',
});Option B — Ship prebuilt binaries for all Node major versions
Use @mapbox/node-pre-gyp or prebuild-install to bundle prebuilt .node binaries for Node 22 and 25 on both darwin-arm64 and linux-x64, so the plugin never needs to compile at install time.
Option C — Document Node version pinning
Add a clear note in README + installation docs recommending that users pin the same Node major version for both the npm installation environment and the Gateway service. Provide instructions for locking Node via nvm or Homebrew services.
Workaround (temporary)
Manually rebuild using the same Node binary that the Gateway uses:
cd ~/.openclaw/extensions/memos-local-openclaw-plugin
/opt/homebrew/opt/node/bin/node /opt/homebrew/opt/node/bin/npm rebuild better-sqlite3
# Then restart gateway
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gatewayBut this needs to be repeated every time the plugin or OpenClaw is updated.
Priority
This is a blocking issue for any user whose OpenClaw Gateway runs under Node 25, which is the default Homebrew Cellar version on macOS. Given that Node 22 is LTS and Node 25 is the current macOS default for Homebrew users, this likely affects a significant portion of users.
Activity
Memtensor-AI commentedon May 28, 2026
✅ AutoDev task
00fcf7cad23cddc1completed.Summary: 已修复 Issue #1734：memos-local-openclaw 插件现在使用 process.execPath 强制 npm rebuild 走 Gateway 当前 Node 二进制，彻底避免 PATH 上的 npm 误用其他 Node 版本导致的 NODE_MODULE_VERSION ABI 不匹配。新增 9 个单元测试，全部通过。
Base branch:
v2.0.16Branch:
autodev/MemOS-1734Commit:
b69bac6PR: #1818
Assigned to: @CarltonXiang, @syzsunshine219
Reviewers: @CarltonXiang, @syzsunshine219
Memtensor-AI commentedon Jun 3, 2026
🤖 AutoDev has picked up this issue and started working on it.
Task ID:
84d80788f95ea3bfWorking branch:
autodev/MemOS-1734Target branch:
mainWorkflow: opsp (analysis → coding → testing → PR)
I will post the PR link here once done. If I need more information, I will ask in the comments.
fix: upgrade better-sqlite3 to 12.10.0 for Node.js 25 support
Memtensor-AI commentedon Jun 3, 2026
🚀 AutoDev task
84d80788f95ea3bfpushed commit.Summary: Fixed better-sqlite3 native module ABI mismatch on Node.js 25 by upgrading to version 12.10.0.
Root Cause:
Both memos-local-plugin and memos-local-openclaw were using better-sqlite3 v12.6.3, which lacks prebuilt native binaries for Node.js 25. Additionally, memos-local-openclaw had an explicit engine constraint blocking Node.js 25.
Changes Made:
Verification:
The fix ensures users on Node.js 25 will receive prebuilt native binaries during installation, eliminating ABI mismatch errors.
Base branch:
mainBranch:
autodev/MemOS-1734Commit:
32fac6fI will create the PR next and post the PR link here.
Memtensor-AI commentedon Jun 3, 2026
✅ AutoDev task
84d80788f95ea3bfcompleted.Summary: Fixed better-sqlite3 native module ABI mismatch on Node.js 25 by upgrading to version 12.10.0.
Root Cause:
Both memos-local-plugin and memos-local-openclaw were using better-sqlite3 v12.6.3, which lacks prebuilt native binaries for Node.js 25. Additionally, memos-local-openclaw had an explicit engine constraint blocking Node.js 25.
Changes Made:
Verification:
The fix ensures users on Node.js 25 will receive prebuilt native binaries during installation, eliminating ABI mismatch errors.
Base branch:
mainBranch:
autodev/MemOS-1734Commit:
32fac6fPR: #1875
Assigned to: @MatthewZhuang, @CarltonXiang, @syzsunshine219
Reviewers: @MatthewZhuang, @CarltonXiang, @syzsunshine219
Fix #1734: [Bug] better-sqlite3 native module ABI mismatch breaks plu…
Fix MemTensor#1734: [Bug] better-sqlite3 native module ABI mismatch b…