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

messages: text content blocks must be non-empty

The full response is a 400 with the standard Anthropic error envelope. Nothing about it is ambiguous once you know that the prefix before the colon is a path into the request you sent.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages: text content blocks must be non-empty"
  }
}

Anthropic does not publish a catalogue of these strings, so the table below is assembled from reproduced API responses in public issue reports, checked August 2026. The wording is exact; the index numbers vary with your request.

Where empty content blocks actually come from

Nobody writes {"type": "text", "text": ""} on purpose. Every occurrence is a byproduct, and there are four common generators.

1. The tool-only assistant turn

This is the big one. When Claude answers with a tool call and no prose, the assistant turn contains a tool_use block and nothing else. Frameworks that model an assistant message as "text plus optional tool calls" reconstruct it with an empty string in the text slot, and it round-trips fine right up to the moment you replay that history into a follow-up request.

{
  "role": "assistant",
  "content": [
    { "type": "tool_use", "id": "toolu_01A...", "name": "read_file",
      "input": { "path": "src/main.py" } },
    { "type": "text", "text": "" }
  ]
}

2. Replayed transcripts

Any system that persists conversations and rehydrates them later can lose content in the round trip: a database column that trims, a JSON serializer that writes null for an empty list, a summarization pass that replaces a message body with its summary and forgets one branch. The failure is not at write time, when the record still looks plausible, but on the next request that replays it. The index in messages.17: is your fastest route to the culprit.

3. Trimming and context management

Context-window management that truncates messages will eventually truncate one to zero characters. Same for a redaction step that strips secrets from tool output, or a filter that removes thinking blocks and leaves the container behind. A whitespace-preserving trimmer produces the subtler variant, where a message survives as a single newline and earns you must contain non-whitespace text instead.

4. Streaming that ended early

A stream interrupted by an overload or a dropped connection can leave a partially materialized assistant message with an empty text block. Retrying by appending to that fragment sends the empty block straight back to the API. Discard incomplete turns rather than repairing them. This is the direct link between a 529 and a 400 that shows up an hour later.

The fix: sanitize once, at the boundary

Patching each call site fails because there are more call sites than you think and new ones arrive with every feature. Put one function between your message store and the API, and make it the only path.

def sanitize(messages):
    out = []
    for msg in messages:
        content = msg["content"]
        if isinstance(content, str):
            if content.strip():
                out.append({"role": msg["role"], "content": content})
            continue

        blocks = []
        for b in content:
            # text blocks must be non-empty AND non-whitespace
            if b.get("type") == "text" and not b.get("text", "").strip():
                continue
            blocks.append(b)

        # a message emptied by that filter must not be sent at all
        if blocks:
            out.append({"role": msg["role"], "content": blocks})

    # the final assistant turn may not end in whitespace
    if out and out[-1]["role"] == "assistant":
        last = out[-1]["content"]
        if isinstance(last, list) and last and last[-1].get("type") == "text":
            last[-1]["text"] = last[-1]["text"].rstrip()

    return out

A second guard worth adding at the same boundary: assert that the array is non-empty and starts with a user turn. Both are cheap, both catch a real class of bug, and both produce a stack trace pointing at your code instead of a 400 pointing at an index.

Role alternation, and why the docs and the errors disagree

This is worth stating carefully, because the honest answer is more useful than the confident one. Anthropic's Messages API reference says:

And yet roles must alternate between "user" and "assistant" and first message must use the "user" role are both still being reported in July and August 2026. The pattern in those reports is that they arrive through Bedrock, Vertex, or a proxy rather than through api.anthropic.com directly. The most defensible reading: the first-party API merges consecutive turns, and other serving paths enforce strict alternation.

• Always alternate, always start with a user turn. Treat it as a portability requirement, not a first-party rule. It costs nothing and it is the difference between code that survives a move to Bedrock and code that does not.
• There is no system role in the Messages API. System prompts go in the top-level system parameter. A message with "role": "system" is a 400, and it is a very common porting bug coming from an OpenAI-shaped codebase.
• Merge before you send if your agent naturally produces consecutive user turns, for example a user message plus an injected context block. Concatenate them into one message rather than relying on the server to do it.

Tool blocks: the pairing rules and their exact errors

Tool use adds two hard structural rules, and the API states them inside the error messages themselves rather than in a reference table. Both are worth quoting because the wording tells you precisely what to check.

messages.0.content.0: unexpected `tool_use_id` found in `tool_result` blocks:
toolu_01SH5hUP1jreQezT5q4R4yQh. Each `tool_result` block must have a
corresponding `tool_use` block in the previous message.

messages.216: `tool_use` ids were found without `tool_result` blocks immediately
after: tooluse_NudlJpcjeQemU5wudkIYMA. Each `tool_use` block must have a
corresponding `tool_result` block in the next message.

max_tokens, context, and the parameters that started 400ing

The remaining 400s are parameter problems, and two of them changed recently enough that working code can start failing without you touching it.

A max_tokens above the model ceiling is a hard 400 naming both numbers. Input that alone exceeds the context window is prompt is too long: N tokens > M maximum. What changed is the overlap case: on Claude 4.5 and newer, input plus max_tokens exceeding the window is accepted, and generation simply stops with stop_reason: "model_context_window_exceeded" if it gets there. Older models returned a validation error instead. Code written against the old behaviour that reserved headroom defensively is not wrong, just no longer necessary.

Thinking configuration has its own generation-specific rejections, each of which tells you what to use instead: "thinking.type.enabled" is not supported for this model on 4.7 and later, and adaptive thinking is not supported on this model on 4.5 and earlier. If you support more than one model generation, resolve thinking parameters from a per-model table rather than a single global default.

Questions people ask

Keep reading

Continue through Errors and fixes with You exceeded your current quota, please check your plan and billing details.