API 400 on paste-image-without-text: empty text block persists in transcript, breaks all subsequent turns

[loungecrasher]

Pasting image without accompanying text produces empty text block → API 400 on next turn

Summary

When the user pastes an image into Claude Code 2.1.x without typing any accompanying text, the resulting user message's content array contains an image block followed by an empty text block ({"type":"text","text":""}). The message sends successfully the first time, but every subsequent turn in that session re-sends the full transcript to the API, which rejects it with:

400: messages: text content blocks must be non-empty

(older variant on earlier paste-failures also produces: cache_control cannot be set for empty text blocks)

The session becomes unusable until the transcript JSONL file is manually repaired on disk.

Affected version

Claude Code 2.1.112 (current as of 2026-04-18). Likely all 2.1.x — bug observed since at least 2.1.90.

Reproduction

1. Open any Claude Code session
2. Paste an image (screenshot, copied file, etc.) into the prompt
3. Hit enter WITHOUT typing any text
4. (First turn may succeed)
5. Send any further user message
6. API rejects with 400 "text content blocks must be non-empty"

Evidence from our transcripts

After repairing two sessions, the corrupt blocks all matched this pattern:

{
  "role": "user",
  "content": [
    {"type": "image", "source": {...}},
    {"type": "image", "source": {...}},
    {"type": "text", "text": ""}    ← bug
  ]
}

Sometimes one image, sometimes 2+, always with a trailing empty text block.

Expected behavior

Either:

• A: client strips the empty text block before adding to transcript (preferred)
• B: client inserts a placeholder text block with minimal content (e.g., "(image attachment)")
• C: API accepts empty text blocks on user messages when the array contains non-empty blocks

Impact / frequency

Single user, 10 agents on one host. Our most-paste-heavy agent hit this 8+ times in one day (running Sprint 14 review with screenshots). Each occurrence requires manual intervention on the JSONL file. We've built an auto-repair hook as a stopgap but the bug is in the client serialization, not the transcript.

Environment

• macOS 15.x (Darwin 25.x)
• Apple Silicon (M4)
• Terminal.app and iTerm2 both affected
• Codeman (web UI) sessions also affected

Workarounds currently in use

1. Manual: always type at least one character alongside pasted images (easy to forget)
2. Automated: UserPromptSubmit hook that scans the transcript for empty text blocks and strips them before each API call (working, but shouldn't be necessary)

Root-cause hypothesis

The paste handler likely always appends a trailing text block to the content array regardless of whether text was entered. If the text input is empty, the block is added with text: "" instead of being omitted.

Suggested fix

In the message serialization path, if the content array would end with an empty text block AND contains at least one non-text block before it, drop the empty text block before serialization.

[0xbrainkid]

Image paste without accompanying text producing {"type":"text","text":""} in the content array — making every subsequent API call fail with 400 "text content blocks must be non-empty" — is the same session-locking pattern as #49026 (interrupted tool call left malformed message), #49876/#50347 (malformed JSONL lines silently truncating sessions), and #50010 (400 from empty text on image-only messages).

All of these share the same root cause: malformed message content written to the JSONL transcript, causing every subsequent API call (which re-sends the full transcript) to fail with 400.

The fix has two required parts:

1. Never write empty text blocks. Before writing a message to the transcript, validate that all text content blocks have non-empty text fields. If a block has "text": "", either remove the block or skip writing the message until it has valid content. The empty block is created by the paste-without-text flow — that flow should produce a content array with only the image block, not image + empty text.

2. Transcript sanitization on message failures. When the API returns 400 "text content blocks must be non-empty," the harness should automatically detect and remove the offending empty blocks from the transcript before retrying, rather than leaving the session in an unrecoverable state. The same defensive parsing strategy as Session resume silently truncates model context at null-byte padding from interrupted append #49876 applies: corrupt/invalid content blocks should be skipped or removed, not cause infinite 400 failures.

Manual recovery for this session: Find the JSONL file at ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. Find the message that contains an image block followed by {"type":"text","text":""}. Either delete the empty text block from that JSON object, or delete the entire message. Save the file and restart the session.

Related: #50010 is a duplicate for the same 400 on image-only messages — both would be fixed by the same validation step.

[github-actions]

Found 3 possible duplicate issues:

1. Empty text block in session JSONL causes unrecoverable session corruption on resume #41992
2. API 400 error when submitting image-only message (empty text content block) #50010
3. [Bug] Anthropic API Error: Empty Text Content Block in Messages #49171

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[lmntltools]

+1 Windows data point (existing report is tagged macOS only — this reproduces identically on Windows).

• Windows 10 Pro 19045, Git Bash shell
• Max 20x subscriber — hit this 3 times this week, each occurrence kills the working session and requires spinning up a new worktree
• Request IDs for tracing the 400s:
  • req_011CaHrkkVsvsRfQHZfbFh3o
  • req_011CaHrsPkeoNZazjdzB5ZxZ

Also confirming: the "type any character alongside the image" guidance only prevents new poisoning. Once the empty text block is in the JSONL, every subsequent turn replays the full transcript and 400s — adding text on later messages does not recover the thread. The only in-session recovery is manually patching the JSONL (per @0xbrainkid's comment above).

Bumping for priority — thread-killer for paid-tier users.