fix: Add Node.js 25+ compatibility warning for V8 WASM compiler bugs

colbymchenry · colbymchenry · commit 7507605be55d · 2026-04-07T14:02:19.000-05:00
Addresses potential crashes on Node.js 25+ due to V8 turboshaft WASM compiler issues. Adds runtime version check with warning to recommend Node.js 22 LTS and sets upper bound engine constraint to
diff --git a/package.json b/package.json
@@ -54,6 +54,6 @@
     "sqlite-vss": "^0.1.2"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.0.0 <25.0.0"
   }
 }
diff --git a/src/bin/codegraph.ts b/src/bin/codegraph.ts
@@ -50,6 +50,22 @@ async function loadCodeGraph(): Promise<typeof import('../index')> {
 const importESM = new Function('specifier', 'return import(specifier)') as
   (specifier: string) => Promise<typeof import('@clack/prompts')>;
 
+// Warn about unsupported Node.js versions (Node 25+ has V8 turboshaft WASM bugs)
+const nodeVersion = process.versions.node;
+const nodeMajor = parseInt(nodeVersion.split('.')[0] ?? '0', 10);
+if (nodeMajor >= 25) {
+  console.warn(
+    '\x1b[33m⚠\x1b[0m  CodeGraph may crash on Node.js %s due to a V8 WASM compiler bug in Node 25+.',
+    nodeVersion
+  );
+  console.warn(
+    '   Please use Node.js 22 LTS instead: https://nodejs.org/en/download'
+  );
+  console.warn(
+    '   See: https://github.com/colbymchenry/codegraph/issues/81\n'
+  );
+}
+
 // Check if running with no arguments - run installer
 if (process.argv.length === 2) {
   import('../installer').then(({ runInstaller }) =>

Original file line number	Diff line number	Diff line change
`@@ -54,6 +54,6 @@`
`54`	`54`	`"sqlite-vss": "^0.1.2"`
`55`	`55`	`},`
`56`	`56`	`"engines": {`
`57`		`- "node": ">=18.0.0"`
	`57`	`+ "node": ">=18.0.0 <25.0.0"`
`58`	`58`	`}`
`59`	`59`	`}`