SQLite database corruption (database disk image is malformed) when running concurrent sessions on NFS

[jerry-xu0514]

Bug Report

OpenCode version: latest (as of 2026-02-24)
OS: Linux 6.6.105+ (NFS-mounted home directory)
Runtime: Bun

Description

Opening multiple opencode sessions in the same repository corrupts the shared SQLite database (~/.local/share/opencode/opencode.db), making opencode unable to start until the database is manually deleted.

Error

{
  "name": "UnknownError",
  "data": {
    "message": "SQLiteError: database disk image is malformed\n    at values (unknown)\n    at get (../../node_modules/.bun/drizzle-orm@1.0.0-beta.12-a5629fb+1f516382cd87cd66/node_modules/drizzle-orm/bun-sqlite/session.js:91:25)\n    at run (node:async_hooks:62:22)\n    at use (src/storage/db.ts:111:28)\n    at fromDirectory (src/project/project.ts:193:26)\n    at async <anonymous> (src/project/instance.ts:27:52)\n    at async provide (src/project/instance.ts:40:23)\n    at processTicksAndRejections (native:7:39)"
  }
}

Steps to Reproduce

1. Have opencode installed with home directory on NFS
2. Open an opencode session in a repository
3. Open a second opencode session in the same (or different) repository
4. Send a message in either session
5. SQLite database corrupts almost immediately — opencode crashes with the above error
6. All subsequent attempts to start opencode also crash until the database is manually deleted

Root Cause (Suspected)

All opencode sessions share a single SQLite database (~/.local/share/opencode/opencode.db) using WAL mode. Concurrent writers likely cause corruption due to:

1. NFS + SQLite locking: SQLite relies on POSIX fcntl() advisory locking, which is notoriously unreliable on NFS. The WAL -shm file uses shared memory mappings that don't work correctly over network filesystems.
2. bun-sqlite concurrency: Even on local filesystems, multiple processes writing to the same bun-sqlite database without explicit coordination (e.g., PRAGMA busy_timeout, retry logic, or a single-writer architecture) can corrupt the database.

Evidence of NFS involvement: stale .nfs* handle files were present alongside the corrupted database in ~/.local/share/opencode/.

Workaround

Delete the corrupted database and let opencode recreate it (loses all session history):

rm ~/.local/share/opencode/opencode.db ~/.local/share/opencode/opencode.db-shm ~/.local/share/opencode/opencode.db-wal

Suggested Fixes

• Set PRAGMA busy_timeout to handle concurrent access gracefully instead of corrupting
• Use PRAGMA journal_mode=DELETE instead of WAL when on a network filesystem (or detect NFS and warn)
• Consider per-project databases instead of a single global one
• Add integrity checks on startup with a graceful recovery path instead of crashing

Related Issues

• Concurrent sessions working on different repos interfer each other #4251 — Concurrent sessions interfere with each other (session isolation)
• Sessions are not saving with multi sessions on #5241 — Sessions not saving with multiple sessions open
• OpenCode API Race Condition in Concurrent Session Deletion #5517 — Race condition in concurrent session deletion

[jerry-xu0514]

Follow-up Investigation (2026-02-25) — Third Corruption Incident

The corruption has occurred again today (Feb 25), the third time in one week. Sessions were running in separate repositories this time. Posting detailed findings with clear separation of observed facts vs. inferences.

---

Observed Facts

1. The database is on NFS — confirmed

$ df -T ~/.local/share/opencode/
Filesystem                         Type  ...  Mounted on
10.125.224.2://shared_home/jerryxu nfs   ...  /mnt/home

$ stat --file-system ~/.local/share/opencode/
  Type: nfs

$ python3 -c "... statfs() ..."
  f_type: 0x6969 (NFS magic number)

NFS mount options: vers=3, local_lock=none, proto=tcp, nconnect=7, hard

2. The current database is corrupted right now

$ PRAGMA integrity_check
*** in database main ***
Tree 12 page 12: unable to get the page. error code=522
Tree 6 page 59: unable to get the page. error code=522

Database stats: 122 pages × 4096 bytes = 500KB main db, WAL = 2.7MB (656 frames), SHM = 32KB.

The database was recently recreated after the previous corruption (only 2 sessions, 18 messages, 71 parts exist) — meaning it corrupted again almost immediately after recovery.

3. Six stale .nfs* handle files — physical evidence of the corruption mechanism

~/.local/share/opencode/
  .nfs...7700000062  45MB   Feb 18 16:36  (corrupted db, incident #1)
  .nfs...7800000064  5.1MB  Feb 18 18:32  (its WAL file)
  .nfs...7900000063  32KB   Feb 18 18:32  (its SHM file)

  .nfs...0200000091  191MB  Feb 24 15:25  (corrupted db, incident #2)
  .nfs...5600000093  5.7MB  Feb 24 15:33  (its WAL file)
  .nfs...5700000092  32KB   Feb 24 15:33  (its SHM file)

These .nfs* files are NFS "silly rename" artifacts. They are created when a file is deleted (rm) while another process still has it open. NFS cannot truly delete the file, so it renames it to .nfsXXXX and deletes it when the last file handle closes.

This means: when the corrupted database was deleted to recover, at least one other opencode process still had the database file open. This confirms concurrent multi-process access was occurring.

Note the database sizes grew dramatically between incidents: 45MB → 191MB, which is consistent with unchecked WAL growth from uncoordinated concurrent writers.

4. Installed opencode v1.2.14 has no NFS protection

$ opencode --version
1.2.14

$ strings $(which opencode) | grep -c "resolveDbDir"
0

$ strings $(which opencode) | grep -c "isNFS"
0

The installed binary does not contain any NFS detection, integrity check, or fallback logic.

5. PRAGMA busy_timeout IS set in the source code

The original issue suggested adding busy_timeout — it's actually already there (PRAGMA busy_timeout = 5000). This pragma is not sufficient to prevent corruption on NFS because the problem is not lock contention timeout but rather incoherent shared memory (the -shm mmap). busy_timeout only helps when locks work correctly but are held by another process; on NFS, the locks themselves are unreliable.

6. WAL checkpoint behavior reveals the corruption mechanism

On first connection via python3, integrity check failed (errors above). On second connection moments later, integrity check passed and all tables were readable. This is consistent with WAL-index (-shm) corruption rather than main database file corruption: the second connection rebuilt the WAL index from scratch, recovering the data. This is exactly the failure mode described in SQLite's documentation on WAL mode over network filesystems — the -shm shared memory mappings become incoherent across NFS clients.

---

Inferences (not directly observed, but strongly supported)

1. The corruption is caused by WAL mode on NFS, not by a concurrency bug in opencode's code. The .nfs* stale handles, the -shm file corruption pattern, and the NFS mount type all point to this. SQLite's own documentation explicitly warns against this configuration.

2. Sessions on different repos still collide because all projects share one global database file (~/.local/share/opencode/opencode.db). Even if the sessions are logically independent, they write to the same SQLite file and contend for the same WAL/SHM.

3. The corruption can happen with a single session on NFS if the process crashes or is killed without cleanly closing the database, leaving the WAL in an inconsistent state that the next process cannot recover from over NFS. (Though multi-session definitely makes it more likely.)

---

Assessment of Proposed Fixes

We've prototyped fixes locally (not yet released). Here's what they do and whether they'd work:

Fix 1: NFS detection + /tmp fallback

function isNFS(dir: string): boolean {
  return statfsSync(dir).type === 0x6969
}

function resolveDbDir(): string {
  if (!isNFS(Global.Path.data)) return Global.Path.data
  const localDir = path.join(os.tmpdir(), "opencode-" + os.userInfo().uid)
  mkdirSync(localDir, { recursive: true })
  return localDir
}

Would this fix the corruption? Yes. We confirmed that statfsSync().type returns 0x6969 on this system, so the detection works correctly. Moving the database to /tmp avoids NFS entirely, and WAL mode works perfectly on local filesystems.

Trade-off: /tmp is ephemeral — session history is lost on machine reboot. For our use case (ephemeral dev containers), this is acceptable. For persistent workstations with NFS home dirs, a configurable local path (e.g., OPENCODE_DATA_DIR env var) would be better.

Fix 2: Integrity check + auto-recreation on startup

const result = sqlite.prepare("PRAGMA integrity_check").get()
if (result?.integrity_check !== "ok") {
  sqlite.close()
  removeDatabase(dbPath)
  sqlite = new BunDatabase(dbPath, { create: true })
}

Would this prevent the hard crash? Yes. Instead of crashing with "database disk image is malformed", opencode would detect the corruption, log a warning, delete the database, and start fresh. This is defense-in-depth — it doesn't prevent corruption but makes it self-healing.

Would this prevent data loss? No. The database is still recreated from scratch; all session history is lost. But at least the user doesn't have to manually intervene.

Fix 3 (not implemented): PRAGMA journal_mode = DELETE on NFS

An alternative to the /tmp fallback. DELETE mode doesn't use shared memory mappings, so it's more NFS-compatible. However, it's slower for concurrent reads and still relies on NFS advisory locks, which are fragile. We chose the /tmp approach as more robust.

---

Recommendation

Ship fixes 1 + 2 together:

• NFS detection + local fallback prevents the root cause
• Integrity check provides resilience even on local filesystems (e.g., power loss, OOM kills)
• Consider adding an OPENCODE_DB_PATH or OPENCODE_DATA_DIR env var override for users who want control over where the database lives

Timeline

• Feb 18: First corruption, manually deleted db to recover
• Feb 24: Second corruption, manually deleted db to recover
• Feb 25: Third corruption (current), sessions on separate repos