Skip to content

Instantly share code, notes, and snippets.

@marcello-russo
Last active October 15, 2026 08:37
Show Gist options
  • Select an option

  • Save marcello-russo/0b3bd4872a9eac4b0c31ebf7dc332c01 to your computer and use it in GitHub Desktop.

Select an option

Save marcello-russo/0b3bd4872a9eac4b0c31ebf7dc332c01 to your computer and use it in GitHub Desktop.
Recovering sessions after the OpenCode V1 to V2 migration (troubleshooting guide)

Recovering sessions after the OpenCode V1 → V2 migration

After upgrading to OpenCode 2.0, pre-upgrade sessions may vanish from the TUI picker. They are usually not lost: they remain in the V1 tables and the migration stopped halfway, or migrated rows no longer match the TUI's filters. This guide covers diagnosis and repair.

# Set once per shell. Defaults:
#   Linux:   ~/.local/share/opencode
#   macOS:   ~/Library/Application Support/opencode
#   Windows: %LOCALAPPDATA%\opencode
export OPENCODE_DATA=~/.local/share/opencode   # adjust for your OS

SQLite database (WAL mode): $OPENCODE_DATA/opencode.db. V1 tables: session, message, part. V2 tables: session_v2, session_message.

Back up first (online backup, safe while the service runs): sqlite3 "$OPENCODE_DATA/opencode.db" ".backup '$OPENCODE_DATA/opencode.db.bak-DATE'" The file can exceed 10 GB — check free space first. For writes, prefix PRAGMA busy_timeout=60000 if you hit database is locked.

0. Assess

SELECT count(*) FROM session;      -- V1 sessions
SELECT count(*) FROM session_v2;   -- migrated sessions
SELECT count(*) FROM session_v2 WHERE parent_id IS NULL;  -- top-level (most rows are subagent children)
  • session ≫ session_v2 → migration incomplete, data intact.
  • opencode api get "/api/experimental/migration/v1" → completed or not.
  • grep "V1 migration failed" "$OPENCODE_DATA/log/opencode.log"

1. An invalid message ID aborts the migration

One off-format ID (e.g. msg-init1 instead of msg_init1) fails Session.Message.ID validation and aborts the whole run. Log shows V1 migration failed ... starting with "msg_".

SELECT id, session_id FROM message WHERE id NOT GLOB 'msg_*';  -- GLOB, not LIKE: _ is a LIKE wildcard
SELECT id FROM part WHERE id NOT GLOB 'prt_*';
PRAGMA busy_timeout=60000;
BEGIN;
UPDATE message SET id='msg_init1' WHERE id='msg-init1';
UPDATE part SET message_id='msg_init1' WHERE message_id='msg-init1';
COMMIT;

Then opencode service restart — the migration resumes and completes.

2. Sessions stuck on the global project

V1 rows carry project_id='global'; the TUI picker filters by current project (project + subpath params — see packages/tui/src/component/dialog-session-list.tsx).

SELECT project_id, count(*) FROM session_v2 WHERE directory='/your/project' GROUP BY project_id;
CREATE TABLE IF NOT EXISTS _backup_session_project AS SELECT id, project_id FROM session_v2;  -- rollback snapshot
UPDATE session_v2 SET project_id = (SELECT p.id FROM project p WHERE p.worktree = session_v2.directory)
WHERE project_id='global'
  AND EXISTS (SELECT 1 FROM project p WHERE p.worktree = session_v2.directory);

3. Stale path (subpath) field

The TUI requests subpath='' (path relative to the project worktree); migrated rows keep the old path relative to / (e.g. home/user/project). Check with the exact TUI query:

opencode api get "/api/session?project=<ID>&subpath="   # should include old sessions
PRAGMA busy_timeout=60000;
UPDATE session_v2 SET path=''
WHERE project_id!='global' AND path!=''
  AND directory=(SELECT worktree FROM project WHERE id=session_v2.project_id);

Then opencode service restart, quit and reopen the TUI.

4. Directories with no project row

SELECT s.directory, count(*) FROM session_v2 s LEFT JOIN project p ON p.worktree=s.directory
WHERE s.project_id='global' AND p.id IS NULL GROUP BY s.directory;

The server creates the project row on first TUI open in that directory (IDs are random — never invent them). Open each directory once in the TUI, then repeat §2–§3.

5. Verify

  • opencode session list from the project directory shows old top-level sessions.
  • No fresh level=ERROR ... V1 migration failed in the log (ignore spawning process lines echoing your own grep).
  • PRAGMA integrity_check; → ok.

Notes

  • Large DBs (10+ GB) are normal — bulk is message part content; never drop tables to free space.
  • Sessions under unmounted volumes can't be remapped until reconnected.
  • Multiple TUIs don't corrupt data, but a stale one shows a stale list; keep exactly one open.
  • Upstream: a single legacy ID should not abort migration, and migration should remap project + path itself (tracked in the linked issue).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment