Skip to content
BENIBIX Learn

MAX_STRUCTURED_OUTPUT_RETRIES

AI⌨️ Claude CodeConfiguration

Also known as MAX_STRUCTURED_OUTPUT_RETRIES environment variable

It sets how many tries the model gets to match a schema.

Think of it like

It is like you give a child five tries to fill in a form right.

Example

Jack's job waits a long time when the model keeps missing his schema. He sets this to 2, so it fails fast and he can fix the schema.

Why it matters

Each retry costs time and tokens. A cap stops a bad schema from burning both.

Definition

MAX_STRUCTURED_OUTPUT_RETRIES sets how many tries Claude Code gets to match a JSON schema. It counts in print mode with --json-schema, and for workflow subagents. The default is 5, which is one try and four retries. After that many misses, the run fails.

Example code

bash
export MAX_STRUCTURED_OUTPUT_RETRIES=2
claude -p --json-schema schema.json "List the open bugs"
Fail fast if the shape is wrong twice.

Common mistake

Setting it to 1 and expecting a retry. One means a single try with no retry.

Key takeaways

  1. 1
    Default 5. One try, four retries.
  2. 2
    Print mode. With --json-schema.
  3. 3
    Then it fails. No valid output.