How to Automatically Repair Invalid LLM Responses

Fix malformed LLM JSON with deterministic repair before you pay for a re-ask. Presets, repair headers, and payload-shape telemetry show exactly what changed.

November 18, 2026

Related templates: Repair High Volume JSON Agent

Picture an on-call thread, an illustrative scenario, that opens with "the model got worse." Pass rate on the invoice agent is flat, latency is flat, and the provider has shipped nothing. What has climbed is the re-ask count, and finance spots the token bill first.

Nothing is wrong with the answers. The model is drifting on format: JSON wrapped in a markdown fence, a trailing comma, a number returned as a string, an enum value in the wrong case. Each of those fails a strict validator, and each re-ask pays for another full completion.

This article covers how deterministic response repair handles that class of failure in ValGuard, where it stops, and how to roll it out. The short version: fix shape with code, keep meaning in validators, and leave re-ask as the last option.

Many invalid responses are format failures

Structured output validation catches two different problems. Some responses are wrong: a missing invoice total, a made-up customer ID. Others are right but badly encoded, so the data is there and the parser cannot read it.

Re-ask treats both the same way. It sends validator feedback back to the model and hopes the next completion is clean. That adds latency, tokens, and unpredictability, because a second completion can fix the comma and break something else.

Format failures do not need a model. A trailing comma has one correct repair, and a fenced JSON block has one correct body. That is the case for LLM JSON repair as a deterministic step on the proxy path.

Repair runs in code, before validation

ValGuard applies response repair after the upstream call returns and before validators run, in process and without a network call. The repaired text is what validators score. If it passes, the request completes without a re-ask. If it still fails, the agent's normal on_fail behavior applies, so block still blocks.

The repair rules are grouped into three tiers. A preset decides which tiers an agent may use.

TierWhat it doesEnabled by
Tier 1, syntaxTrims whitespace, extracts JSON from a markdown fence, normalizes smart quotes, fixes single quotes, unquoted keys, trailing and leading commas, and missing commas between quoted values on separate linesSafe, Standard, or Custom
Tier 2, schema-awareCasts numeric and boolean strings, normalizes enum casing, fills configured defaults, normalizes dates, currency, and country codes, clamps to configured bounds, truncates arrays to configured maximumsStandard, or Custom
Tier 3, field-scopedClamps numeric ranges, converts amounts to cents, generates deterministic UUIDv5 values for empty ID fieldsCustom only, per named field

Tier 2 and Tier 3 only run when the output parses as JSON after Tier 1. Repair never edits a field inside a document that still cannot be parsed.

Tier 2 reads the agent's JSON Schema rule plus hints from field validators such as range_validator, enum_validator, and list_length. Defaults are never invented: a field is filled only when a default is configured for it.

Presets are set per agent or inherited from the workspace, and both start at Off. Response repair is also off at the platform level by default; the agent's Response Repair tab appears once an admin enables it.

A concrete example

Here is a response from an invoice agent whose schema expects amount as a number and status as one of paid or open. The model wrapped it in a markdown fence labeled json.

{"invoice_id": "INV-4471", "amount": "1250.00", "status": "Paid",}

Safe extracts the fenced body and removes the trailing comma. The document now parses, but amount is still a string and Paid is not an allowed value, so validators still fail it.

Standard goes one step further. It casts "1250.00" to the number 1250 and maps Paid to paid, because the enum match ignores case. The validators then see a clean object, and no extra model call is needed.

Standard does not map Payed to paid. Near-match enum repair only runs on fields you opt into fuzzy matching; other values outside the allowed list still fail.

What Standard changes, and what it can cost

Safe is low risk because its rules only touch syntax. Standard changes values, and some of those changes deserve a careful read first.

If an agent has a range_validator with a minimum or maximum, Standard can clamp an out-of-range number to that bound instead of letting the validator block it. If a list_length rule sets a maximum, Standard can truncate the array. These changes are deterministic and logged, but they change values.

When a range violation must block, use Custom instead and leave the clamp and truncation rules off.

Standard also has one non-deterministic behavior. When the only enforcing failures are invalid-format errors, it may spend one extra model call asking for well-formed JSON. That is a re-ask, and a successful one is recorded as reask:valid_format.

What repair will not fix

Response repair fixes shape, not meaning.

  • A required field with no configured default stays missing, so validation still blocks. The model is not asked to invent the value.
  • The one narrow exception covers required email and name fields. Repair can copy a value only if it appears verbatim in the conversation, never from the model's own guess.
  • A semantically wrong value that is well formed, such as the wrong total, passes through repair unchanged.
  • Repair does not touch policy rules such as PII detection or forbidden phrases. Those run on the repaired text and block as configured.
  • Tier 3 never runs unless a field is named in a Custom allowlist.

If the model routinely omits a field, that is a prompt or extraction problem. Repair should not hide it.

Every fix leaves a record

Repair follows the same explainability rule as validators. Each fix produces a log event with a rule ID, a field path where one applies, and before and after snippets redacted according to the agent's log level.

Response headers separate "repair ran" from "repair made the request pass." The OpenAI-compatible response body keeps its shape; only the assistant content is replaced with the repaired text.

HeaderWhen it is set
X-VG-Repair-AttemptedRepair changed the payload, whatever the final verdict
X-VG-Repair-Rules, X-VG-Repair-TraceRule IDs, and rule@field entries, for the attempt
X-VG-HealedThe final response passed and repair contributed to it
X-VG-Healed-Rules, X-VG-Healed-Event-CountRules and event count behind the passing response

When validation still blocks after repair, the healed headers are cleared. A blocked request is never labeled as repaired.

Request rows store healed, heal_rules, heal_field_paths, and post_heal_validation_pass. The request log has a Repaired column, request detail lists the rules that fired, and the proxy exports valguard_response_repair_total by rule.

A rollout that keeps validators in charge

Repair changes what validators see, so treat a preset change like a validator change.

  1. Measure first. Read payload_shape telemetry for the agent. It records json_valid and a parse_error_type such as trailing_comma, without storing content.
  2. Enable Safe on one agent. Pick a high-volume JSON agent where format failures drive re-asks.
  3. Change one thing at a time. Leave validator on_fail settings alone in the same window.
  4. Compare re-asks and blocks. Re-asks should fall without more bad business data getting through.
  5. Read Standard's rules before promoting. Check whether clamps, truncation, or defaults would touch fields that should block.
  6. Reserve Tier 3 for named fields. Allowlist a field only when its owner agrees with the transform.

payload_shape is computed on the text validators score, which is the repaired text when a preset is on. A rising json_valid=false count with repair enabled means repair is not covering the failure.

Repair presets have no observe-only mode of their own: when a preset is on, clients receive the repaired text. Shadow mode belongs to validators, so test rule changes with Simulate, as in test policy before production.

The dashboard walkthrough is in self-healing without re-ask. To estimate savings at your volume, use the response repair calculator.

Using the repair playbooks

Five published playbooks support this rollout. Each is a two-step triage flow: an extraction agent structures the incident context, and a handoff agent packages it for a human reviewer.

They are checklists for a human decision. They do not change presets, cap re-asks, or block traffic on their own.

What this is not

  • Response repair is not a validator. It never replaces the validators that enforce your rules.
  • It is not an LLM step. Tier 1 to Tier 3 are code, and the one format re-ask in Standard is labeled separately.
  • It is not proof that every rule ran. For that, see how to measure AI guardrail coverage.
  • It is not a fix for schema drift. When failure types change after a provider update, detect LLM schema drift first.

Start with one agent

Pick one agent where tickets mention invalid JSON but model evals look fine. Check its parse error types, enable Safe, and watch re-ask counts and the Repaired column for a few days. Move to Standard only after you know which values it would change.

For why blind retries make this worse, read the retry logic that made latency worse. For multi-agent flows, see self-healing multi-agent AI systems.

Book a technical walkthrough with our team → Start free in shadow mode — no credit card →

Related articles

Shadow Mode Is Not Coverage

Shadow mode shows what would block before enforce. It does not prove every configured validator ran on every request. Use coverage attribution for chain completeness.

How to Measure AI Guardrail Coverage

Measure which production traffic actually ran your full validator chain — not just which rules exist on the agent. Full-chain %, gap lists, CSV export, and shadow vs coverage.

Why Hashing Tool Calls Won't Catch Your Agent's Loops

Hashing tool calls only catches exact repeats. Near-identical retries, busy-looking non-progress, and retries/fallbacks outside the counter all slip past it. Progress checks, an outside budget, and an end-state check stop them.