Skip to content

Commit f52a3e3

Browse files
committed
docs(sandbox): document opencode.db image-upgrade remediation
Follow-up to agent-of-empires#2650 (fix agent-of-empires#2605). Reviewer Seluj78 flagged an acknowledged trade-off in the merged fix: emptying clean_files for the opencode data-dir mount also drops the container-image-update reset the struct doc originally described. If a future image bump ships an opencode release whose drizzle migrations are not forward-compatible with the pre-existing sandbox DB, opencode aborts on boot. This is not hypothetical - the same failure class is observed upstream on standalone opencode CLI upgrades (anomalyco/opencode#31119, #16678). Add a Troubleshooting entry to docs/guides/sandbox.md following the existing Symptoms/Cause/Fix shape (matches the OOM entry), with: - The failing scenario symptoms - Root cause chain: sandbox DB persists (agent-of-empires#2605) -> drizzle forward-only -> incompatible migration on old DB -> boot abort - One-line remediation: rm -f ~/.local/share/opencode/sandbox/opencode.db{,-wal,-shm} - Reactive framing (rare event, most upgrades migrate cleanly) - Upstream anomalyco/opencode issue references so the entry ages with evidence rather than speculation Docs-only, no code impact, no test impact.
1 parent 83d110c commit f52a3e3

1 file changed

Lines changed: 14 additions & 0 deletions

File tree

‎docs/guides/sandbox.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -265,3 +265,17 @@ Git worktrees need the bare repo pattern so the container can reach the repo's g
265265
The `MEM LIMIT` column should reflect your configured value.
266266

267267
**Note:** On Linux, Docker runs natively without a VM, so the memory ceiling is your host's physical RAM. You typically only need `memory_limit` on Linux to prevent a single container from consuming all system memory.
268+
269+
### Sandboxed OpenCode fails to start after a container-image upgrade
270+
271+
**Symptoms:** After bumping the sandbox container image, launching or resuming a sandboxed OpenCode session fails on boot with a drizzle or SQLite migration error (e.g. `no such column`, `CREATE TABLE ... already exists`, `Failed to run the query`). Non-sandboxed OpenCode sessions on the same host are unaffected.
272+
273+
**Cause:** The sandboxed OpenCode SQLite database at `~/.local/share/opencode/sandbox/opencode.db{,-wal,-shm}` persists across sessions so that `aoe resume` keeps `ses_*` identity working across kills and daemon restarts (see #2605). OpenCode manages its schema with drizzle, and drizzle migrations are forward-only. If the new image ships an OpenCode release whose forward migrations are not compatible with the pre-existing DB, OpenCode aborts on boot. This is the same failure class users hit on standalone OpenCode CLI upgrades (see upstream anomalyco/opencode#31119 and anomalyco/opencode#16678); the sandbox-image bump is just another version-change vector.
274+
275+
**Fix:** Delete the sandboxed OpenCode DB and restart the session. Only the sandboxed OpenCode chat history is lost; host OpenCode state (outside the `sandbox/` subdir) is untouched.
276+
277+
```bash
278+
rm -f ~/.local/share/opencode/sandbox/opencode.db{,-wal,-shm}
279+
```
280+
281+
**Note:** This is a rare event tied to breaking schema changes in OpenCode releases; most upgrades migrate cleanly. If you hit it repeatedly on the same image bump, please file an issue upstream at `anomalyco/opencode` with the migration error output.

0 commit comments

Comments
 (0)