# Atlas StructuredOutputError: structured output could not be parsed after retries > Simplify the requested schema: Atlas raises StructuredOutputError only after the retry budget is exhausted, and deeply nested or ambiguous shapes fail more often. 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. ## Symptom A structured-output request fails with StructuredOutputError, which carries both a message and a retries count. ## Cause Atlas retries when the model returns output that does not decode against the requested schema. When the retry budget is exhausted, Atlas raises StructuredOutputError with the number of attempts made recorded in the retries field. ## Fix 1. Simplify the requested schema. Deeply nested or ambiguous shapes fail to decode more often than flat, explicit ones. 2. Use a model with stronger structured-output support, then re-run the same request. 3. Inspect the retries field on the StructuredOutputError to see whether the model failed every attempt or only the last one. 4. Fall back to a free-text response plus a parsing step if the provider cannot honor the schema at all. 5. Re-run the request after each change so you can attribute the improvement to one edit rather than several. ## 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. ## FAQ ### 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. --- Canonical HTML: https://runatlas.sh/resources/troubleshooting/structured-output-error Source of truth: aeo_pages row `/resources/troubleshooting/structured-output-error` (segment: Troubleshooting) (this file is generated from it, never hand-edited). Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.