[BUG] 400 error: cache_control cannot be set for empty text blocks

Preflight Checklist

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

What's Wrong?

I’m encountering a recurring API error when using Claude Code:

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.1124.content.6.text: cache_control cannot be set for empty text blocks"}}

Context:

• Using Claude Code (latest version)
• Running inside a WebSocket-based agent system (OpenClaw gateway)
• Multi-message / multi-block conversations (large message arrays)

Observed behavior:
Claude Code appears to sometimes generate or send a content block like:

{
"type": "text",
"text": "",
"cache_control": { "type": "ephemeral" }
}

This results in a hard failure from the Anthropic API:
"cache_control cannot be set for empty text blocks"

Expected behavior:

• Claude Code should not generate empty text blocks, OR
• It should strip cache_control from empty/whitespace-only blocks before sending

Impact:

• Entire request fails (not partial)
• Breaks agent pipelines and real-time workflows
• Requires manual sanitization before sending

Temporary workaround:
We fixed it by filtering content blocks before sending:

messages = messages.map(m => ({
...m,
content: Array.isArray(m.content)
? m.content.filter(b => b.type !== "text" || b.text?.trim())
: m.content
}));

Additional notes:

• Happens intermittently (not every request)
• More frequent in long-running sessions (1000+ messages)
• Likely occurs during internal content block construction

This affects production agent systems relying on Claude Code for real-time workflows.

What Should Happen?

I’m encountering a recurring API error when using Claude Code:

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.1124.content.6.text: cache_control cannot be set for empty text blocks"}}

Context:

• Claude Code (latest version)
• WebSocket-based agent system (OpenClaw gateway)
• Large multi-message conversations

Observed behavior:
Claude Code sometimes sends a content block like:
{
"type": "text",
"text": "",
"cache_control": { "type": "ephemeral" }
}

This causes the request to fail with:
"cache_control cannot be set for empty text blocks"

Expected:

• No empty text blocks should be sent, OR
• cache_control should not be applied to empty blocks

Impact:

• Entire request fails
• Breaks real-time agent workflows

Workaround:
We filter out empty text blocks before sending.

Notes:

• Happens intermittently
• More frequent in long sessions (1000+ messages)

Error Messages/Logs

Steps to Reproduce

1. Start a long-running Claude Code session or agent workflow that builds large multi-message payloads with multiple content blocks.

1. Include at least one message whose content array contains a text block that ends up empty ("") or whitespace-only after block construction/transformation.

1. Apply cache_control to text content blocks before sending the request.

1. Send the request through Claude Code / Anthropic API.

1. Observe the request fail with:

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"messages.1124.content.6.text: cache_control cannot be set for empty text blocks"}}

Minimal example of the bad payload pattern:

{
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "",
"cache_control": { "type": "ephemeral" }
}
]
}
]
}

Expected result:
The client should either remove empty text blocks before sending, or strip cache_control from empty/whitespace-only text blocks.

Actual result:
The entire request fails with a 400 invalid_request_error.

Claude Model

None

Is this a regression?

Yes, this worked in a previous version

Last Working Version

_No response_

Claude Code Version

Claude Code v2.1.97

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_