claude-code - 💡(How to fix) Fix [BUG] API Error 400 "cache_control cannot be set for empty text blocks" — triggered by multi-image upload in single message

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

Summary

When attaching multiple images (screenshots) to a single message in Claude Code on the web (<claude.ai/code>), the session can permanently break with:

API Error: 400 messages.N.content.M.text:
  cache_control cannot be set for empty text blocks

Once it hits, EVERY subsequent message in that session returns the same 400 because the corrupted content block is replayed in the conversation history. Retries do not work — the session is effectively dead.

Reproduction

1. Open a new session at <claude.ai/code> in a project
2. Attach 4-5 screenshots to a single message (drag-and-drop or paste)
3. Type a short prompt with the images and send
4. The first error may appear immediately, or on a later turn

I reproduced this twice:

• Once at message #818 in a long-running session (<claude.ai/code/session_01MXfh2WVnGwts7tPjdNCVBg>)
• Once at message #4 in a fresh session after uploading 5 thumbnails in one turn

Single-image messages do NOT trigger it.

Expected behavior

Multi-image messages should serialize as multiple content blocks, none of which should be empty text blocks with cache_control set. The platform's message-building code should either:

• Not emit empty text content blocks, OR
• Not apply cache_control to empty blocks

Actual behavior

One of the generated content blocks is an empty text block with cache_control set, which Anthropic's API rejects with HTTP 400. The bad block becomes permanently part of the conversation history, making the session unrecoverable.

Impact

• Lost work: sessions with significant in-progress context die unrecoverably
• Wasted turns: "Try again" and follow-up messages all hit the same 400
• Hard to diagnose: the error message blames "empty text blocks" but the user attached images, not text

Workaround discovered

• Send screenshots one per message instead of batching
• When a session locks up, abandon it (start fresh) — the corruption is baked into that session's history

Environment

• Platform: <claude.ai/code> (web)
• Browser: Safari (iPad) and Chrome (Windows desktop) — both affected
• Model: Claude Opus 4.7 (1M context)
• First observed: 2026-05-21

What Should Happen?

Summary

When attaching multiple images (screenshots) to a single message in Claude Code on the web (<claude.ai/code>), the session can permanently break with:

API Error: 400 messages.N.content.M.text:
  cache_control cannot be set for empty text blocks

Once it hits, EVERY subsequent message in that session returns the same 400 because the corrupted content block is replayed in the conversation history. Retries do not work — the session is effectively dead.

Reproduction

1. Open a new session at <claude.ai/code> in a project
2. Attach 4-5 screenshots to a single message (drag-and-drop or paste)
3. Type a short prompt with the images and send
4. The first error may appear immediately, or on a later turn

I reproduced this twice:

• Once at message #818 in a long-running session (<claude.ai/code/session_01MXfh2WVnGwts7tPjdNCVBg>)
• Once at message #4 in a fresh session after uploading 5 thumbnails in one turn

Single-image messages do NOT trigger it.

Expected behavior

Multi-image messages should serialize as multiple content blocks, none of which should be empty text blocks with cache_control set. The platform's message-building code should either:

• Not emit empty text content blocks, OR
• Not apply cache_control to empty blocks

Actual behavior

One of the generated content blocks is an empty text block with cache_control set, which Anthropic's API rejects with HTTP 400. The bad block becomes permanently part of the conversation history, making the session unrecoverable.

Impact

• Lost work: sessions with significant in-progress context die unrecoverably
• Wasted turns: "Try again" and follow-up messages all hit the same 400
• Hard to diagnose: the error message blames "empty text blocks" but the user attached images, not text

Workaround discovered

• Send screenshots one per message instead of batching
• When a session locks up, abandon it (start fresh) — the corruption is baked into that session's history

Environment

• Platform: <claude.ai/code> (web)
• Browser: Safari (iPad) and Chrome (Windows desktop) — both affected
• Model: Claude Opus 4.7 (1M context)
• First observed: 2026-05-21

Error Messages/Logs

Steps to Reproduce

Summary

When attaching multiple images (screenshots) to a single message in Claude Code on the web (<claude.ai/code>), the session can permanently break with:

API Error: 400 messages.N.content.M.text:
  cache_control cannot be set for empty text blocks

Once it hits, EVERY subsequent message in that session returns the same 400 because the corrupted content block is replayed in the conversation history. Retries do not work — the session is effectively dead.

Reproduction

1. Open a new session at <claude.ai/code> in a project
2. Attach 4-5 screenshots to a single message (drag-and-drop or paste)
3. Type a short prompt with the images and send
4. The first error may appear immediately, or on a later turn

I reproduced this twice:

• Once at message #818 in a long-running session (<claude.ai/code/session_01MXfh2WVnGwts7tPjdNCVBg>)
• Once at message #4 in a fresh session after uploading 5 thumbnails in one turn

Single-image messages do NOT trigger it.

Expected behavior

Multi-image messages should serialize as multiple content blocks, none of which should be empty text blocks with cache_control set. The platform's message-building code should either:

• Not emit empty text content blocks, OR
• Not apply cache_control to empty blocks

Actual behavior

One of the generated content blocks is an empty text block with cache_control set, which Anthropic's API rejects with HTTP 400. The bad block becomes permanently part of the conversation history, making the session unrecoverable.

Impact

• Lost work: sessions with significant in-progress context die unrecoverably
• Wasted turns: "Try again" and follow-up messages all hit the same 400
• Hard to diagnose: the error message blames "empty text blocks" but the user attached images, not text

Workaround discovered

• Send screenshots one per message instead of batching
• When a session locks up, abandon it (start fresh) — the corruption is baked into that session's history

Environment

• Platform: <claude.ai/code> (web)
• Browser: Safari (iPad) and Chrome (Windows desktop) — both affected
• Model: Claude Opus 4.7 (1M context)
• First observed: 2026-05-21

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

No response

Claude Code Version

Web version

Platform

Anthropic API

Operating System

Other

Terminal/Shell

Other

Additional Information