aft doctor crashes with ERR_FS_FILE_TOO_LARGE when OpenCode opencode.db exceeds 2 GiB

[flyinghail]

Short description

aft doctor crashes with ERR_FS_FILE_TOO_LARGE when OpenCode's opencode.db exceeds Node's 2 GiB file read limit.

What happened?

aft doctor crashes when the OpenCode SQLite database at ~/.local/share/opencode/opencode.db is larger than Node's 2 GiB single-file read limit.

Initially, my opencode.db had grown to 58,196,938,752 bytes (~54.2 GiB) due to excessive OpenCode event history. Running aft doctor produced:

node:fs:401
      throw new ERR_FS_FILE_TOO_LARGE(size);
            ^

RangeError [ERR_FS_FILE_TOO_LARGE]: File size (58196938752) is greater than 2 GiB
    at tryCreateBuffer (node:fs:401:13)
    at readFileSync (node:fs:501:14)
    at visit (file:///usr/lib/node_modules/@cortexkit/aft/dist/index.js:12059:17)
    at snapshotTree (file:///usr/lib/node_modules/@cortexkit/aft/dist/index.js:12061:3)
    at snapshotOperatorState (file:///usr/lib/node_modules/@cortexkit/aft/dist/index.js:12066:15)
    at probeOpenCodeV1Version (file:///usr/lib/node_modules/@cortexkit/aft/dist/index.js:12072:18)
    at detectOpenCodeHostGeneration (file:///usr/lib/node_modules/@cortexkit/aft/dist/index.js:12131:95)
    at OpenCodeAdapter.detectHostGeneration (file:///usr/lib/node_modules/@cortexkit/aft/dist/index.js:12288:28)
    at detectOpenCodeForCommand (file:///usr/lib/node_modules/@cortexkit/aft/dist/index.js:16039:55)
    at runFixFlow (file:///usr/lib/node_modules/@cortexkit/aft/dist/index.js:16694:25) {
  code: 'ERR_FS_FILE_TOO_LARGE'
}

Node.js v24.19.0

I traced the process with strace, which showed that aft doctor stats and then opens opencode.db immediately before the crash:

statx(... "~/.local/share/opencode/opencode.db", ..., stx_size=58196938752, ...) = 0
openat(... "~/.local/share/opencode/opencode.db", O_RDONLY|O_CLOEXEC) = 26
statx(26, "", ..., stx_size=58196938752, ...) = 0

I then used opencode-db-prune to remove the excessive OpenCode event history. After pruning, opencode.db was reduced to 4,391,555,072 bytes (~4.09 GiB), but aft doctor still fails because the database remains above Node's 2 GiB file-read limit.

This makes the underlying AFT issue clearer: aft doctor should not read the entire OpenCode SQLite database into memory as a regular file.

I expected aft doctor to complete its diagnostics regardless of the database size. If it only needs the database size or metadata, it should use stat. If database contents need to be inspected, it should query SQLite directly or otherwise avoid loading the complete database file into memory.

At minimum, an oversized database should be skipped or reported as a diagnostic warning instead of causing aft doctor to terminate.

The original OpenCode database growth is a separate OpenCode issue. Pruning reduced it substantially, but a legitimate multi-gigabyte SQLite database can still exceed Node's 2 GiB whole-file read limit. This report is specifically about aft doctor attempting to read opencode.db in a way that cannot handle such databases.

Diagnostics

Plugin version

0.56.0

AFT binary version

0.56.0

Platform

linux x64

Log output (optional)

[timothyclin]

seeing the same here too

[aft-alfonso]

Confirmed and fixed on main; thanks for the strace — it named the site exactly.

The crash is in aft doctor's OpenCode V1 version probe. Before running the probe it snapshots your live ~/.local/share/opencode as a canary, so that if the probed host ever wrote to your real database or logs the probe fails loudly instead of silently corrupting them. That snapshot hashed every byte with readFileSync, which is fine for a log directory and impossible for a multi-gigabyte SQLite file — hence ERR_FS_FILE_TOO_LARGE before any diagnostic ran. Your read is right: the canary needs to detect change, not to own the bytes.

What changed:

• bytes are hashed through a 1 MiB window instead of a whole-file read, so memory is bounded regardless of database size;
• files up to 64 MiB are still hashed whole; larger ones contribute their head and tail plus size and mtime, which still moves the digest when SQLite rewrites its header page or appends;
• a per-file read failure (permissions, a file vanishing mid-probe) is recorded in the digest instead of terminating doctor;
• the canary now also watches opencode.db-wal and opencode.db-shm, since in WAL mode a write lands in the sidecar first — that was a real hole in the check.

Verified with a 3 GiB database fixture: the probe completes and resident memory grows by less than 256 MiB; restoring the old whole-file read pushes it to 6.4 GB, which is what the regression test asserts.

Ships in the next release. Your opencode.db growth is indeed an OpenCode-side matter, but doctor should never have cared how large it was.

[aft-alfonso]

Released in 0.56.1 — npx @cortexkit/aft@latest doctor on that version no longer reads your database at all.

Published: npm @cortexkit/aft@0.56.1 (and the plugin packages), crates.io agent-file-tools@0.56.1, and the GitHub release with its per-asset checksums.

If you still see ERR_FS_FILE_TOO_LARGE after upgrading, the stack trace will name a different call site than snapshotTree/snapshotOperatorState and I would want it — this fix covers the operator-state canary only, and there is no reason for any other part of doctor to read a database whole, so a second occurrence would be a second bug rather than a regression of this one.

Thanks again for the strace. It turned a report into a one-site fix.