# MAX_STRUCTURED_OUTPUT_RETRIES

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

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** MAX_STRUCTURED_OUTPUT_RETRIES environment variable

## Think of it like

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

## 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

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.

## 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.

## Why it matters

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

## Common mistake

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

## Three principles

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

## Related terms

- [--json-schema Flag](https://learn.benibix.com/term/ai/json-schema-flag)
- [Structured Output (LLM)](https://learn.benibix.com/term/ai/structured-output)
- [--output-format Flag](https://learn.benibix.com/term/ai/output-format-flag)

---

Source: https://learn.benibix.com/term/ai/max-structured-output-retries-variable
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-17
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
