Node.js v24 Compatibility Issue - better-sqlite3 Build Failure

[jjohare]

Environment

• OS: Linux (CachyOS) 6.17.3-3-cachyos
• Node.js: v24.9.0
• npm: 11.6.2
• node-gyp: v11.5.0
• GCC: 15.2.1
• Python: 3.13.7
• Package: [email protected]

Problem Description

Installation of claude-flow@alpha fails on Node.js v24.9.0 due to native compilation errors in the better-sqlite3 dependency (used by agentdb). The build process fails with multiple C++ compilation errors related to deprecated V8 APIs.

Steps to Reproduce

1. Install Node.js v24.9.0
2. Run: npm install -g claude-flow@alpha
3. Observe compilation failure

Error Output

npm error code 1
npm error path /usr/lib/node_modules/claude-flow/node_modules/agentdb/node_modules/better-sqlite3
npm error command failed
npm error command sh -c prebuild-install || node-gyp rebuild --release

Key Compilation Errors

./src/util/macros.lzz:31:69: error: 'CopyablePersistentTraits' is not a member of 'v8'
./src/better_sqlite3.lzz:37:104: error: 'struct Addon' has no member named 'SqliteError'
/root/.cache/node-gyp/24.9.0/include/node/v8config.h:13:2: error: #error "C++20 or later required."
./src/util/binder.lzz:132:78: error: no matching function for call to 'v8::String::Utf8Value::Utf8Value(v8::Isolate*&, v8::Local<v8::String>&)'

Full Error Log

Click to expand full compilation error

In file included from ../src/better_sqlite3.cpp:4:
./src/util/macros.lzz:31:69: error: 'CopyablePersistentTraits' is not a member of 'v8'; did you mean 'NonCopyablePersistentTraits'?
./src/util/macros.lzz:31:94: error: template argument 2 is invalid
./src/util/macros.lzz:31:51: error: '<expression error>' in namespace 'v8' does not name a type
./src/util/macros.lzz:149:2: error: 'v8::AccessorGetterCallback' has not been declared; did you mean 'v8::AccessorNameGetterCallback'?
[... truncated for brevity ...]
make: *** [better_sqlite3.target.mk:118: Release/obj.target/better_sqlite3/src/better_sqlite3.o] Error 1
gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

Root Cause Analysis

1. Node.js v24 Breaking Changes: Node.js v24 removed several deprecated V8 APIs including:

   • v8::CopyablePersistentTraits (replaced with NonCopyablePersistentTraits)
   • v8::AccessorGetterCallback (replaced with v8::AccessorNameGetterCallback)
   • Changed v8::String::Utf8Value and v8::Object::Get signatures

2. C++20 Requirement: Node.js v24 requires C++20 standard, but better-sqlite3 doesn't properly configure this in its build process

3. Dependency Chain:

   [email protected]
   └── agentdb (dependency)
       └── better-sqlite3 (native module)
   

4. better-sqlite3 Version: The version pinned by agentdb is incompatible with Node.js v24's V8 engine changes

Attempted Workarounds (Failed)

1. Manual C++20 Flag

sudo CXXFLAGS="-std=c++20" npm install -g claude-flow@alpha

❌ Still fails - C++20 standard alone doesn't fix deprecated V8 API usage

2. Compiler Override

sudo CXX="g++ -std=c++20" npm install -g claude-flow@alpha

❌ Still fails - same V8 API incompatibility

3. Build from Source

sudo npm install -g claude-flow@alpha --build-from-source

❌ Invalid npm flag in recent versions

Working Solution

Downgrade to Node.js v22 LTS (Jod)

# Arch Linux / CachyOS
sudo pacman -S nodejs-lts-jod --ask 4

# Verify
node --version  # v22.19.0

# Install claude-flow
sudo npm install -g claude-flow@alpha

# Success!
claude-flow --version  # v2.7.0-alpha.14