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.
opencode --session <id>oropencode 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.
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();"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);"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.
- Bun ≥ 1.1 (installed at
~/.bun/bin/bun, add to PATH) - Git
- ~4GB available RAM (for the compile step)
# 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();"| 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 |
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.
- 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). Usermthencp— 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.
Two files are modified:
-
packages/opencode/src/provider/transform.ts— ThenormalizeMessagesfunction already filtered empty text blocks, but only for@ai-sdk/anthropicand@ai-sdk/amazon-bedrockproviders. The fix makes this filter universal (applies to ALL providers includinggithub-copilot). -
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.
| 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 |
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