Skip to content

Commit d278b2c

Browse files
committed
Update TROUBLESHOOTING.md
1 parent 1314c01 commit d278b2c

File tree

1 file changed

+8
-21
lines changed

1 file changed

+8
-21
lines changed

docs/TROUBLESHOOTING.md

Lines changed: 8 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -45,10 +45,12 @@ If the app crashes with something like:
4545
libc++abi: terminating due to uncaught exception of type Napi::Error
4646
```
4747

48-
Native modules (like node-pty) need to be rebuilt for your Electron version:
48+
Native modules (like node-pty) need to be rebuilt for your Electron version.
49+
50+
### Fix
4951

5052
```bash
51-
pnpm --filter code exec electron-rebuild
53+
cd apps/code && npx electron-rebuild -f
5254
```
5355

5456
## Codex agent crashes with GPU process errors
@@ -70,37 +72,22 @@ node apps/code/scripts/download-binaries.mjs
7072

7173
Then restart the app. This downloads the codex-acp binary to `apps/code/resources/codex-acp/`, which gets copied to `.vite/build/codex-acp/` during build.
7274

73-
## Database initialization failed (better-sqlite3 bindings not found)
75+
## Database initialization failed (better-sqlite3)
7476

75-
If you see this error on startup:
77+
If you see either of these errors on startup:
7678

7779
```
7880
Database initialization failed Error: Could not locate the bindings file.
7981
```
8082

81-
The `better-sqlite3` native binary wasn't compiled for your Electron version. This commonly happens after a merge, branch switch or fresh install because the postinstall rebuild can fail silently (`|| true`).
82-
83-
### Fix
84-
85-
```bash
86-
npx @electron/rebuild -f -m node_modules/better-sqlite3
87-
```
88-
89-
Then restart the app.
90-
91-
## NODE_MODULE_VERSION mismatch after Electron upgrade
92-
93-
If you see an error like:
94-
9583
```
9684
Database initialization failed Error: The module '.../better_sqlite3.node'
9785
was compiled against a different Node.js version using
9886
NODE_MODULE_VERSION 145. This version of Node.js requires
99-
NODE_MODULE_VERSION 123. Please try re-compiling or re-installing
100-
the module (for instance, using `npm rebuild` or `npm install`).
87+
NODE_MODULE_VERSION 123.
10188
```
10289

103-
A native module (usually `better-sqlite3`) was compiled against your system Node instead of Electron's bundled Node. This happens after pulling an Electron version bump because `electron-rebuild` picked up the wrong Node binary.
90+
The `better-sqlite3` native binary wasn't compiled for your Electron version. This commonly happens after a merge, branch switch or Electron upgrade because the postinstall rebuild can fail silently (`|| true`).
10491

10592
### Fix
10693

0 commit comments

Comments
 (0)