How should an agent recover when the previous turn produced output that failed schema validation?

Flashcard·Medium·4.0 · 0·~30s·Asked atAda Qdrant Reliance Jio

Attempt it

Do not just resend the same prompt and hope. Append the failed output verbatim, the validator's structured error (which field, which constraint, what got received), and an instruction to return only the corrected JSON, no commentary. The model now has the exact diff it needs to fix. Keep the original task and any retrieved evidence in context so the repair stays grounded. Cap the retry count (usually 1-2) and fall back to a safe default if the model cannot self-repair, repair attempts that hide the bug burn tokens and quality.

Your answer

When model output fails schema validation, the wrong response is to **resend the same prompt and hope for better luck**. The model has no reason to produce different output a second time, the prompt is identical and the model is approximately deterministic given the same prompt and temperature. The right response gives the model the **specific information it needs to repair**. Four pieces of context should be in the repair turn. **1. The original task and any retrieved evidence.** Keep the context that produced the original answer so the repair stays grounded. If the original task was 'extract these fields from this document,' the document still needs to be in context. **2. The model's failed output verbatim.** The model needs to see what it produced so the repair is a diff against that, not a regeneration from scratch. **3. The validator's structured error.** Not 'your JSON is invalid', that gives no actionable information. The error should name the field, the constraint that failed, and what was received. Something like: ``` Validation error: field: user.email constraint: must match email format received: "not-an-email" ``` **4. A clear instruction.** Something like 'Return only the corrected JSON, no commentary or explanation.' The instruction should ask for the smallest possible repair, not a rewrite. With this context the model has the exact diff to apply. It usually succeeds on the next call. **Cap the retries.** One or two attempts at self-repair is reasonable. Past that, the model is stuck, either the schema is too strict for what the data actually contains, or the task is harder than a repair loop can handle. Fall back to a **safe default**: skip the field, use a placeholder, route to human review. Repair loops that run forever burn tokens without delivering value.

Schema validation failures are one of the cleanest examples of where good context engineering separates working agents from broken ones. The right recovery turn gives the model **specific, structured information** about the failure and asks for a **minimal repair**, not a regeneration. **The four context pieces** that go into the repair turn: **1. The original task and any retrieved evidence.** The model needs to know what it was asked to do and what source material it should ground in. Stripping this and just asking 'fix the JSON' loses the grounding that made the original answer plausible. **2. The failed output verbatim.** The model needs to see exactly what it produced so the repair is a diff against that output. Without it, the model regenerates from scratch and the same error often reappears. **3. The validator's structured error.** This is the most important piece and the one most teams get wrong. Generic errors like 'JSON is invalid' or 'parsing failed' give the model nothing actionable. Structured errors name the field path, the constraint, and the received value: ``` Validation error: field: user.email constraint: must match email format received: "not-an-email" Validation error: field: items[2].quantity constraint: must be positive integer received: -3 ``` When multiple errors are present, list all of them so the model can fix them in one pass rather than ping-ponging. **4. A precise instruction.** Something like 'Return only the corrected JSON. Do not include explanation, commentary, or markdown formatting. Change only the fields that failed validation; keep all other fields unchanged.' The instruction should constrain the model to a minimal repair. **Retry policy.** Cap retries at 1-2 attempts. Production teams in 2026 commonly use a single retry: if the first repair fails, the loop stops. The rationale: when a model fails the same schema constraint twice, it is unlikely to succeed on attempt 3, 4, or 5.

TL;DR

Show the model its failed output verbatim, the validator's structured error pointing at the exact failing field and constraint, the original task and evidence, and request only the corrected JSON, then cap retries

Memory aid

Easy to grasp

Imagine asking a friend to fill out a form and they get one field wrong. The wrong way to fix it is to hand them a blank form and say try again, they will probably make the same mistake. The right way is to hand them their filled-out form back, point at the wrong field, and say what the rule was. Now they can see exactly what to change. If they still cannot get it after one or two tries, do not keep asking forever, fall back to filling it in yourself or skipping the field.

Key concepts

Context Engineering

Concept explanation~2 min read

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.

Schema validation failures are an everyday reality of structured-output agents, and the way an agent responds to them is one of the clearest tests of good context engineering. The right repair turn gives the model specific structured information about the failure and asks for a minimal diff, not a regeneration. The wrong repair turn resends the same prompt with a generic try again and burns tokens on the same failure. This deep dive walks through the four context pieces, the retry policy, the fallback strategies, the role of provider structured-output modes, and the deeper principle that structured-output failures are usually context insufficiencies dressed up as model errors.

The four context pieces of a repair turn

A well-designed repair turn contains exactly four things.

The original task and any retrieved evidence. The model needs to know what it was asked to do and what source material it should ground in. If the task was 'extract these fields from this customer email,' the email is still in context. Stripping the grounding and just asking 'fix the JSON' loses the information that made the original answer plausible and forces the model to guess.

The failed output verbatim. The model needs to see exactly what it produced so the repair is a diff against that output. Without it, the model regenerates from scratch and the same error often recurs. Showing the failed output also lets the model use its own previous reasoning, most of the fields were probably correct, and the repair should preserve them.

The validator's structured error. This is the highest-leverage piece. Generic errors like 'JSON parsing failed' or 'schema validation failed' give the model nothing actionable. Structured errors name the field path, the constraint that failed, and what was received:

code

Validation error:
  field: invoice.line_items[2].unit_price
  constraint: must be positive number
  received: -45.99

Validation error:
  field: invoice.due_date
  constraint: must be valid ISO 8601 date
  received: "next Tuesday"

When multiple errors are present, list all of them so the model can fix them in one pass rather than fixing one and missing another.

A precise instruction. Something like 'Return only the corrected JSON. No commentary, no markdown fencing, no explanation. Change only the fields that failed validation; keep all other fields unchanged.' Each clause closes a common failure mode: 'no commentary' prevents prose preambles, 'no markdown fencing' prevents code-block wrapping, 'change only the fields that failed' enforces minimal repair.

Why diff-style repair beats regeneration

Retry policy and fallback strategies

Provider structured-output modes as first-line prevention

Schema bugs and the deeper context-engineering lesson

Situations where this technique stops working.

2–4 min · Everything important, quickly.

Real products, models, and research that use this idea.

Pydantic AI implements this repair pattern with structured error feedback across providers
Instructor library wraps the failed output plus structured error pattern for Python applications

What an interviewer would ask next. Try answering before peeking at the approach.

QHow would you architect a structured-output pipeline that uses both a constrained-generation mode and a repair fallback?

First-line: use the provider's structured-output mode (Anthropic tool-use, OpenAI structured outputs, Gemini response mime type) with your JSON schema. Most outputs validate on the first call. For the few that fail, fall through to a repair turn that includes the failed output and the structured validator error. Cap the repair turn at one retry. If it still fails, route to the fallback path. Instrument first-attempt success rate, repair success rate, and fallback rate to monitor pipeline health.

2 more follow-ups an interviewer would ask next. Sign in to reveal them.

Red flags & common mistakes

The phrases that signal junior thinking. Click to expand.

Most common mistake

Resending the same prompt with a generic try again message and watching the model produce the same broken JSON until the retry loop burns the budget.

60 second bullets to scan on the way to the call.

Name the four context pieces in a repair turn (task plus evidence, failed output, structured error, instruction)
Explain why a structured error beats a generic try again

Primary sources. Browse if you want the original framing.