Skip to content

fix(runtime): require Node.js 22.14 so the guard catches the better-sqlite3 segfault - #200

Merged
grinev merged 1 commit into
grinev:mainfrom
hcsum:fix/node-version-guard-22-14
Aug 7, 2026
Merged

fix(runtime): require Node.js 22.14 so the guard catches the better-sqlite3 segfault#200
grinev merged 1 commit into
grinev:mainfrom
hcsum:fix/node-version-guard-22-14

Conversation

@hcsum

@hcsum hcsum commented Aug 5, 2026

Copy link
Copy Markdown
Contributor

Problem

On Node.js 22.0–22.13 the bot starts, logs a few lines, then dies with a bare Segmentation fault: 11:

[INFO] Starting OpenCode Telegram Bot v0.22.5...
[INFO] Node.js v22.12.0 on darwin arm64
...
[INFO] [SessionCache] Pruned 9 stale directories from cache
sh: line 1: 63248 Segmentation fault: 11  npm start

The crash is better-sqlite3's prebuilt addon. macOS crash report:

exception: EXC_BAD_ACCESS / SIGSEGV, KERN_INVALID_ADDRESS at 0x90
napi_module_register_by_symbol(...)
node::binding::DLOpen(...)

The prebuild is built against Node-API v10, which only ships from Node.js 22.14. On older 22.x, dlopen faults inside the N-API registration instead of failing cleanly.

getUnsupportedNodeVersionMessage() was meant to catch exactly this before any native addon is imported, but it only parsed the major version, so every 22.x passed the check.

Minimal repro:

node -e "new (require('better-sqlite3'))(':memory:')"   # exit 139

Verified locally across installed minors:

Node result
22.12.0 SIGSEGV (139)
22.13.1 SIGSEGV (139)
22.14.0 OK

Change

  • src/runtime/node-version.ts: compare major and minor against 22.14. Unparseable versions still pass through without blocking startup.
  • tests/runtime/node-version.test.ts: added a case for 22.12.0; minimum-version case is now 22.14.0.
  • package.json: engines.node>=22.14.
  • README.md: badge and prerequisite line → 22.14+.

CI's node-version: 22 already resolves to the latest 22.x, so it is left alone.

Verification

On Node 22.14.0: npm run build, npm run lint, npm run typecheck clean; npm test → 135 files, 1317 tests passed.

🤖 Generated with Claude Code

The startup guard only compared the major version, so Node.js 22.0-22.13
passed the check and then crashed the process with SIGSEGV while loading
better-sqlite3's prebuilt addon. The prebuild needs Node-API v10, which
is only available from Node.js 22.14.

Verified locally with `new Database(':memory:')`:
22.12.0 SIGSEGV, 22.13.1 SIGSEGV, 22.14.0 OK.

Compare major and minor so the guard prints the actionable message
instead of letting the process segfault, and align `engines` and the
README with the real minimum.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@grinev

grinev commented Aug 7, 2026

Copy link
Copy Markdown
Owner

@hcsum thanks for this fix!

@grinev
grinev merged commit 5581a3a into grinev:main Aug 7, 2026
1 check passed
@hcsum
hcsum deleted the fix/node-version-guard-22-14 branch August 8, 2026 03:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants