Integration Guides

API Error 400: System Content Must Contain at Least One Block

ROIBest AI

What “system content must contain at least one block” means

The Claude Messages API error api error: 400 messages.1: system content must contain at least one block means your request reached Anthropic’s API, but the system field on a message (often index 1 in a multi-part client payload) was present as an empty or invalid content value. The API expects system to be either omitted or filled with at least one content block (usually a text block).

This is a client-side request-shape bug, not an outage. Related 400 patterns are covered in Claude API Error 400.

Typical request shapes that trigger it

Common causes in SDKs, gateways, and DIY curl clients:

  1. Empty system string — system: "" or system: [] after your template rendered nothing.
  2. Null / missing block array — you set system to an object without a content array, or content: [].
  3. Wrong message index — some wrappers put system as messages[1]; the .1 in the error points at that slot, not “HTTP/1.1”.
  4. Conditional system prompts — feature flags skip the prompt but still send the system key.
  5. Proxy / gateway mutation — an LLM API gateway or Claude API proxy strips or empties system content while leaving the field present.

Fix checklist (do these in order)

  1. Log the exact JSON body leaving your server (after templating).
  2. If system is empty, omit the field entirely instead of sending "" / [].
  3. If you need a system prompt, send at least one block, for example a text block with non-empty text.
  4. Validate in CI: reject outbound requests where system exists but has zero blocks or blank text.
  5. If you only see the error through a mirror or proxy, compare against a direct Messages call—see timeout / overload cousins in operation timed out and 529 overloaded only after shape validation passes.

Minimal mental model:

  • Omit system when unused.
  • When used, system content length must be ≥ 1 block with real text.

SDK and gateway notes

  • Official SDKs usually accept system as a string and convert it to blocks. Passing an empty string can still serialize into an invalid empty content list depending on version—upgrade and inspect the wire payload.
  • Custom agents that build messages manually often put role system inside messages[]. Anthropic’s Messages API prefers top-level system; stuffing an empty system message into the array is a frequent source of messages.N errors.
  • Multi-tenant gateways should not forward empty per-tenant system templates; drop the key when the tenant config is blank.

How to confirm the fix

Re-send the same user turn with:

  • No system key, or
  • system with one non-empty text block

A valid shape returns 200 with a completion (or a different, unrelated error such as auth or rate limit). If 400 persists with a new message, you fixed this rule and hit the next validation—read the new error.message instead of retrying blindly.

FAQ

Is this an Anthropic outage? Almost never. Empty system content is a request validation failure.

Why does the error say messages.1? It locates the failing field path in the validated body. Check that index in your serialized JSON.

Can I send whitespace-only system text? Do not rely on it. Use a real instruction or omit system.