Skip to content

Instantly share code, notes, and snippets.

@glassdimly
Last active April 1, 2026 16:20
Show Gist options
  • Select an option

  • Save glassdimly/0988483d5de6a09b20e34df7d1d71afe to your computer and use it in GitHub Desktop.

Select an option

Save glassdimly/0988483d5de6a09b20e34df7d1d71afe to your computer and use it in GitHub Desktop.
OpenCode: fix broken sessions (whitespace text parts) — DB nuke + build from source with PR #17742

Fixing Broken Sessions

Error: messages: text content blocks must contain non-whitespace text

When resuming or forking a session fails with this error, it means a whitespace-only text part (e.g. "\n\n") was saved to the session history. The Claude API rejects whitespace-only text content blocks, so the session cannot be replayed.

Symptoms

  • opencode --session <id> or opencode run --session <id> --fork "..." fails immediately with:
    Error: messages: text content blocks must contain non-whitespace text
    
  • The session may have appeared to "hang" or produce empty responses before it broke.

Quick fix: nuke bad parts from DB

Find and delete the bad part(s). Important: SQLite trim() only strips spaces (0x20), not newlines or tabs. Use replace() to catch \n, \r, and \t as well:

# Diagnose: find bad parts in a specific session
sqlite3 ~/.local/share/opencode/opencode.db \
  "SELECT p.id, p.message_id, hex(json_extract(p.data, '$.text')), length(json_extract(p.data, '$.text'))
   FROM part p
   WHERE p.session_id = '<SESSION_ID>'
     AND json_extract(p.data, '$.type') = 'text'
     AND trim(replace(replace(replace(json_extract(p.data, '$.text'), char(10), ''), char(13), ''), char(9), '')) = ''
   ORDER BY p.time_created;"

# Fix: delete bad parts across ALL sessions
sqlite3 ~/.local/share/opencode/opencode.db "
DELETE FROM part 
WHERE json_extract(data, '$.type') IN ('text', 'reasoning') 
  AND (json_extract(data, '$.text') IS NULL 
       OR trim(replace(replace(replace(json_extract(data, '$.text'), char(10), ''), char(13), ''), char(9), '')) = '');
SELECT changes();"

Also check for orphaned messages

The broken text part may belong to an assistant message that also has 0 tokens and no finish reason:

sqlite3 ~/.local/share/opencode/opencode.db \
  "DELETE FROM part WHERE message_id IN (
     SELECT m.id FROM message m
     WHERE m.session_id = '<SESSION_ID>'
       AND json_extract(m.data, '$.role') = 'assistant'
       AND json_extract(m.data, '$.tokens.input') = 0
       AND json_extract(m.data, '$.tokens.output') = 0
       AND (json_extract(m.data, '$.finish') = '' OR json_extract(m.data, '$.finish') IS NULL)
   );
   DELETE FROM message
   WHERE session_id = '<SESSION_ID>'
     AND json_extract(data, '$.role') = 'assistant'
     AND json_extract(data, '$.tokens.input') = 0
     AND json_extract(data, '$.tokens.output') = 0
     AND (json_extract(data, '$.finish') = '' OR json_extract(data, '$.finish') IS NULL);"

Permanent fix: build OpenCode from source with PR #17742

The DB nuke is a band-aid. The real fix is PR #17742 which filters empty text blocks at the API send layer for ALL providers and adds .trim() guards at message construction time. Until this PR is merged into an official release, you need to build from source.

Prerequisites

  • Bun ≥ 1.1 (installed at ~/.bun/bin/bun, add to PATH)
  • Git
  • ~4GB available RAM (for the compile step)

Step-by-step build instructions

# 0. Ensure bun is on PATH
export PATH="$HOME/.bun/bin:$PATH"

# 1. Clone the dev branch (or use existing clone at /tmp/opencode/build/opencode/)
git clone --branch dev --single-branch https://github.com/sst/opencode.git /tmp/opencode/build/opencode

# 2. Cherry-pick the two PR #17742 commits
cd /tmp/opencode/build/opencode
git cherry-pick 1832c280a   # fix(opencode): filter empty text content blocks for all providers
git cherry-pick ef378fa1a   # fix(opencode): preserve adaptive thinking separators
# Both should apply cleanly with no conflicts.

# 3. Install dependencies
cd packages/opencode
bun install --frozen-lockfile
# tree-sitter-powershell native build may fail — this is non-critical, ignore it.

# 4. Build the binary (local platform only)
#    OPENCODE_CHANNEL=latest — CRITICAL: without this, the dev branch builds
#    with channel "dev", which makes the binary use a separate database file
#    (opencode-dev.db) instead of the regular opencode.db. Setting it to
#    "latest" ensures the patched binary uses the same DB as release builds.
#    --single    = build only for current OS/arch (not all 12 targets)
#    --skip-install = skip re-downloading cross-platform native modules
OPENCODE_CHANNEL=latest bun run build --single --skip-install
# Web UI builds first (~7s via Vite), then Bun compiles the binary.
# Total time: ~30-60s depending on hardware.
# Output: dist/opencode-linux-x64/bin/opencode

# 5. Verify the build
dist/opencode-linux-x64/bin/opencode --version
# Should print a version like: 1.3.14 (next patch version from npm registry)

# 6. Install the binary
#    Use rm+cp (not mv or cp over) because the running opencode process
#    holds the old inode open — rm unlinks it safely, cp creates a new inode.
rm ~/.opencode/bin/opencode
cp dist/opencode-linux-x64/bin/opencode ~/.opencode/bin/opencode
chmod +x ~/.opencode/bin/opencode

# 7. Verify installation
~/.opencode/bin/opencode --version

# 8. Nuke any existing bad parts from the DB
sqlite3 ~/.local/share/opencode/opencode.db "
DELETE FROM part 
WHERE json_extract(data, '$.type') IN ('text', 'reasoning') 
  AND (json_extract(data, '$.text') IS NULL 
       OR trim(replace(replace(replace(json_extract(data, '$.text'), char(10), ''), char(13), ''), char(9), '')) = '');
SELECT changes();"

Build flags reference

Flag / Env var Purpose
OPENCODE_CHANNEL=latest Required. Without this, the dev branch defaults to channel dev, which uses a separate DB file (opencode-dev.db). Set to latest so the binary uses the same opencode.db as official releases.
--single Build only for current OS/arch instead of all 12 platform targets
--skip-install Skip bun install --os="*" --cpu="*" for cross-platform native modules (safe if deps already installed)
--skip-embed-web-ui Skip building the SolidJS web UI (produces a binary without the web interface)
--baseline Build baseline binary (no AVX2) instead of native — needed for older CPUs

All sessions missing after installing patched binary?

If you built without OPENCODE_CHANNEL=latest, the binary is using channel dev and reading from opencode-dev.db instead of opencode.db. All your sessions are still in the original DB — they haven't been deleted. Rebuild with OPENCODE_CHANNEL=latest or set the env var at runtime to fix it.

Gotchas

  • Timeout: The Bun compile step can take 30-60s. If running from an AI tool with a timeout, use ≥ 900s (15 min) to be safe. The web UI Vite build (~7s) runs first.
  • Memory: Needs ~4GB available. Check with free -h — the "available" column matters (Linux reclaims buffer/cache). If tight, close other opencode sessions first.
  • Running binary: You cannot overwrite a running binary on Linux (Text file busy). Use rm then cp — the old process keeps its inode open and finishes normally.
  • This session vs new sessions: After replacing the binary, the current running session still uses the old binary. Only NEW sessions will use the patched binary.
  • DB may be locked: If sqlite3 commands fail with "database is locked", other opencode processes hold the lock. The read/write usually works anyway in WAL mode, but if it doesn't, close other sessions first.

What PR #17742 changes

Two files are modified:

  1. packages/opencode/src/provider/transform.ts — The normalizeMessages function already filtered empty text blocks, but only for @ai-sdk/anthropic and @ai-sdk/amazon-bedrock providers. The fix makes this filter universal (applies to ALL providers including github-copilot).

  2. packages/opencode/src/session/message-v2.ts — Adds .trim() guards when constructing text content parts, preventing whitespace-only text from being saved to the DB in the first place. Also adds an adaptive thinking separator safeguard for Sonnet/Opus 4.6.

Backups

File Purpose
~/.opencode/bin/opencode.1.3.10.bak Original 1.3.10 binary (revert target)
~/.local/share/opencode/opencode.db.pre-fix-bak DB before bad-part nuke

Upgrading to official release

Once PR #17742 is merged into a tagged release, replace the dev build:

pkill -f opencode
gh release download vVERSION --repo sst/opencode --pattern 'opencode-linux-x64.tar.gz' --dir /tmp/opencode --clobber
tar xzf /tmp/opencode/opencode-linux-x64.tar.gz -C /tmp/opencode/
rm ~/.opencode/bin/opencode
cp /tmp/opencode/opencode ~/.opencode/bin/opencode
chmod +x ~/.opencode/bin/opencode
~/.opencode/bin/opencode --version
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment