Atlas raises StructuredOutputError when the model returns output that does not decode against the requested schema and the retry budget is exhausted, and the fix is to simplify the schema, because deeply nested or ambiguous shapes fail more often. StructuredOutputError carries both a message and a retries count, so inspect the retries field to see whether the model failed every attempt or only the last, and switch to a model with stronger structured-output support if it failed all of them.
Why does Atlas report StructuredOutputError
Atlas reports StructuredOutputError when a model's output fails to decode against the requested schema and every retry has been used. Atlas retries automatically on a decode failure, and only after the retry budget is exhausted does it raise StructuredOutputError, carrying 2 fields: a message and a retries count.
StructuredOutputError is a last-resort error, not a first-attempt one. Atlas already tried. When a model returns text that will not decode into the shape you asked for, Atlas re-asks rather than failing immediately, and it keeps a count of how many attempts it made. StructuredOutputError only appears once that budget is spent. That framing changes the diagnosis: by the time you see it, the model has repeatedly failed to produce the requested shape, so the schema, the model, or the pairing of the two is the problem. A single unlucky sample would have been absorbed by the retry loop.
How to fix StructuredOutputError in Atlas
Fix StructuredOutputError in Atlas by simplifying the requested schema first, which is step 1 of the 5 documented fix steps, because deeply nested or ambiguous shapes fail more often than flat ones. If a simpler schema still fails, use a model with stronger structured-output support and re-run the identical request.
Schema complexity is the lever you control directly. Deep nesting, unions with unclear discriminators, and fields whose intent is ambiguous from their names all raise the chance the model emits something that will not decode. Flatten the shape, name fields so their content is obvious, and drop optional structure the caller does not actually need. If the schema is already simple and StructuredOutputError still lands, the pairing is wrong: some models honor a requested schema far more reliably than others, and swapping the model is a legitimate fix rather than a workaround.
What the retries count on StructuredOutputError tells you
The retries count on an Atlas StructuredOutputError records how many attempts the model made before the budget was exhausted. Inspect that field to see whether the model failed every attempt or only the last, because those 2 patterns point at different fixes inside Atlas.
A StructuredOutputError where the model failed on every single attempt suggests the model cannot express the requested shape at all, and the answer is a stronger structured-output model or a much simpler schema. A pattern where earlier attempts nearly succeeded and the failures cluster at the edges suggests a schema that is right in principle but ambiguous in one spot, and a targeted simplification of that spot is usually enough. Atlas puts the retries count in the error precisely so this distinction is available without instrumenting anything.
When to fall back to free text instead of structured output
Fall back to a free-text response plus a parsing step in Atlas when the provider cannot honor the schema at all. If StructuredOutputError persists after the 2 earlier remedies, a simpler schema and a model with stronger structured-output support, the schema-constrained path is not viable with that provider.
The fallback trades a guarantee for a chance. A free-text response with your own parsing step will not be validated by the model, so your parser has to be tolerant and must fail loudly when the text does not contain what it expects. That is the honest cost, and it is worth stating: you are moving the decode step from the provider into your own code. But a parsing step that succeeds most of the time beats a structured-output request that raises StructuredOutputError every time, and it keeps the workflow moving while you evaluate a better-suited model.
How to verify the StructuredOutputError fix worked
Verify the StructuredOutputError fix in Atlas by re-running the same structured-output request and confirming it decodes cleanly. Re-run with the original input rather than an easier one, because 1 clean decode on the payload that previously exhausted the retry budget is the confirmation you actually need.
Re-run with the original input, not an easier one, because a simplified test case can decode cleanly while the real payload still blows the retry budget. If StructuredOutputError does not reappear, the fix held. If it does, read the retries count again and compare it to the previous failure: fewer failed attempts than before means the direction is correct even though the schema or the model still needs work, and that is useful signal rather than a dead end.
How to fix it
- 01Simplify the requested schema. Deeply nested or ambiguous shapes fail to decode more often than flat, explicit ones.
- 02Use a model with stronger structured-output support, then re-run the same request.
- 03Inspect the retries field on the StructuredOutputError to see whether the model failed every attempt or only the last one.
- 04Fall back to a free-text response plus a parsing step if the provider cannot honor the schema at all.
- 05Re-run the request after each change so you can attribute the improvement to one edit rather than several.
Frequently asked questions
- What does StructuredOutputError mean in Atlas
- StructuredOutputError means the model returned output that did not decode against the requested schema and Atlas exhausted its retry budget. The error carries both a message and a retries count.
- Does Atlas retry structured output automatically
- Yes. Atlas retries when the model returns output that does not decode against the requested schema. StructuredOutputError is only raised once the retry budget is exhausted, with the number of attempts recorded.
- How do I stop StructuredOutputError from happening
- Simplify the requested schema, since deeply nested or ambiguous shapes fail more often, and use a model with stronger structured-output support if a simple schema still fails.
- What is the retries field on StructuredOutputError for
- The retries field records how many attempts the model made. Inspect it to see whether the model failed every attempt, which points at the model, or only the last, which points at an ambiguous corner of the schema.
- What if my provider cannot honor a schema at all
- Fall back to a free-text response plus a parsing step. That moves the decode into your own code, so the parser must fail loudly, but it avoids StructuredOutputError on a provider that cannot honor the schema.
- Why does a deeply nested schema fail in Atlas
- Deeply nested or ambiguous schemas fail more often because the model has more ways to emit something that will not decode. Flattening the shape reduces StructuredOutputError in Atlas.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Atlas for Godot: Terminal-Native AI Coding for GDScript and the Node Tree in 2026
Atlas is a terminal-native AI coding agent for Godot in 2026, working across GDScript, the node tree, and signals, where scene structure is half the program.
Atlas vs Cline: Terminal AI Coding Agents in 2026
Compare Atlas and Cline, two leading AI coding agents for 2026. Atlas offers terminal-native TUI and permission-gated tools, while Cline integrates with VS Code and provides checkpoint rollbacks.
Migrate a Deprecated API Across Every Callsite with Atlas (2026 Workflow)
How to migrate a deprecated API across every callsite with Atlas in 2026: the lsp tool's findReferences enumerates callers, todowrite tracks them, apply_patch migrates each one.
Atlas with Qwen3 4B (Ollama): 256K of context on a 2.5GB pull in 2026
Qwen3 4B (Ollama) in Atlas: a 2.5GB download carrying 256K tokens (262,144) of context, Free (self-hosted), with separate 2507 instruct and thinking tags.
Atlas with Grok 4.3: The Cheapest 1M Context Reasoning Model (2026)
Grok 4.3 gives Atlas a 1M token context at $1.25 / $2.50 per Mtok, the cheapest 1M reasoning model from a US lab. Output caps at 30,000 tokens, so plan around it.
Atlas with Qwen2.5 72B Instruct: The Flagship Dense Qwen in 2026
Qwen2.5 72B Instruct in Atlas: 128K tokens (131,072), $1.40 per Mtok input, $5.60 per Mtok output, openly published weights you can serve on your own vLLM.
Atlas vs Zed: Terminal AI Coding Agents in 2026
Comparing Atlas, the terminal-native AI coding agent, with Zed, the GPU-accelerated collaborative editor, for developers in 2026. Evaluate their AI autonomy, privacy, and workflow.
Atlas with Qwen3-Next 80B-A3B Thinking: The Reasoning Tier in 2026
Drive Atlas with Qwen3-Next 80B-A3B Thinking: a reasoning trace over 128K tokens (131,072) of context at $0.50 per Mtok input and $6.00 per Mtok output.