JSON Toolkit

JSON Repair Guide: Salvaging Broken LLM Output Without Losing Trust

Bottom line: LLM responses wrapped in markdown fences, trailing commas, and Python literals will not survive a strict parser — neither will hand-edited configs missing quotes. This guide draws the real line between nine error classes a repairer fixes and four it cannot, explains why state machines beat regex, and gives you a production-ready parse chain with jsonrepair and json-repair.

Intermediate~6 min readPublished 2026-11-08Updated 2026-11-08
JSON repair pipeline diagram: fence stripping, quote normalization, bracket balancing, final validation

A strict parser gives broken input zero credit: one error message, one line number, and not a single byte of your data. A repairer exists to turn "total failure" into "good enough to run" — but what it fills in is always a best guess at intent, never a guarantee of correctness.

One: Where Broken JSON Comes From

Repair is not magic, so start with the input. In real projects, non-standard JSON comes from three concentrated sources:

  1. LLM output. Language models generate text token by token; they do not run a JSON serializer. Even when you ask for "JSON only," the model wraps the payload in a ```json fence, prepends "Sure! Here's your data," leaves a trailing comma, or hits the token ceiling and stops in the middle of an object.
  2. Copy-paste from other languages. A JavaScript object logged via console.log carries single quotes and unquoted keys; a Python dict prints as True/False/None. These "JSON-shaped" strings detonate the moment they meet JSON.parse.
  3. JSON5/JSONC configs. Files like tsconfig legally allow comments and trailing commas. Paste one into a strict parser and it rejects the whole file.

The three sources need different handling, but repairers cover all of them — provided the error is on their declared fixable list.

Two: Nine Error Classes a Repairer Actually Fixes

Combining the jsonrepair library documentation with the capability lists published by tool vendors, automatically repairable errors fall into nine classes:

Class Broken input Repaired
Trailing comma [1, 2, 3,] [1, 2, 3]
Single / curly quotes {'a': 'b'} {"a": "b"}
Unquoted keys {name: 'Ada'} {"name": "Ada"}
Comments {"a": 1 /* note */} {"a": 1}
Python literals {"ok": True, "v": None} {"ok": true, "v": null}
Markdown fences ```json {...} ``` {...}
Missing commas [1 2] [1, 2]
Unclosed brackets / strings {"a": [1, 2 {"a": [1, 2]}
JSONP / string concatenation cb({...}), "x" + "y" {...}, "xy"

What these nine have in common: the data is all there; only the syntax is wrong. The repairer adjusts punctuation and wrappers without touching a single value. A few details deserve special attention:

  • Leading-zero numbers become strings. 007 is repaired to "007", not 7, so no digits are lost. If the field is genuinely a textual code, that is correct; if it is a real number, the decision is yours.
  • Bare words become strings. NaN cannot be repaired into a number — some implementations emit "NaN", others null. Behavior differs between libraries; test yours before wiring it into a pipeline.
  • Valid input passes through untouched. Every serious repairer runs a strict-parse fast path first. Valid JSON never enters the repair logic, so there is no "repairing a good document into a bad one."

Three: Four Things a Repairer Cannot Fix

The boundary on the other side is just as explicit. Do not expect repairs for:

  1. HTML error pages or pure prose. There is no JSON structure in the input, and no tool can conjure data out of nothing.
  2. Syntactically valid but wrong data. A misspelled key, a value in the wrong place, a number stored as a string — these are semantic problems that every parser, including repairers, will happily let through.
  3. Data lost to truncation. Completion can turn {"items": [{"id": 1}, {"na into valid JSON, but the name value is gone forever. What you get back is a "valid but incomplete" object. In production, check stopReason === "max_tokens" before deciding whether to complete or retry.
  4. Duplicate keys and ambiguous structures. Which of two identical keys wins depends on the parser implementation. Responsible repairers offer a strict mode that throws instead of silently picking one.

One sentence sums up the trust boundary: repair is a best guess, not a correctness guarantee. Feeding unverified repair output downstream trades a loud syntax error for a quiet data error.

Four: Two Implementation Schools — One URL Settles the Debate

Repairers come in two flavors, and the gap shows up on a specific kind of input.

Regex-replacement school applies global find-and-replace to broken patterns. Consider:

{"url": "http://example.com", 'note': 'fine'}

A regex that converts single quotes to double quotes will chew into the URL; a comment-stripping regex that deletes every // will cut http:// in half. Inside a string and outside a structure, the characters look identical — regex cannot tell them apart.

Character-by-character state machine school tracks a parse state: inside a double-quoted string, inside a single-quoted string, inside a line comment, inside a block comment, or expecting a value. When it sees ', it first asks "am I inside a string?" before deciding whether to convert the quote or skip it. http://example.com sits inside a double-quoted string, so the state machine knows the // is data, not a comment, and preserves it. jsonrepair and json-healer belong to this school, and the community mantra "a repairer is not find-and-replace" refers precisely to this.

The full repair pipeline order (as disclosed by the devkits implementation) is also worth reading: strip fences → normalize curly quotes → extract the first balanced block → remove comments → quote bare keys → drop trailing commas → convert literals → re-serialize with JSON.stringify. That final re-serialization is the key step: no matter what the earlier stages did, output is regenerated from the parsed result, so any downstream strict parser can consume it.

Five: Wiring It Up in Code — A Sequential Parse Chain

When you wire repair into code, the order matters more than the library choice. Following the patterns published by json2toon and aijsonmedic, the sequence should be: truncation check → JSON span extraction → strict parse → repair fallback → schema validation.

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // Repairing truncated output still yields incomplete data — retry instead
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // Extract the JSON span: LLMs may add chatter before and after
  const start = text.search(/[[{]/);
  const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
  const candidate = start >= 0 && end > start ? text.slice(start, end + 1) : text;
  try {
    return JSON.parse(candidate);   // fast path for valid input
  } catch {
    return JSON.parse(jsonrepair(candidate));  // repair fallback
  }
}

On the Python side, the json-repair package (4,700+ stars) offers loads(), which returns an object directly:

from json_repair import repair_json
import json

broken = "{name: 'Ada', tags: ['x',], active: True}"
data = json.loads(repair_json(broken))
# {'name': 'Ada', 'tags': ['x'], 'active': True}

Two engineering details:

  • Align your stacks. If both frontend and backend repair, choose implementations with shared semantics — the Python json-repair and its TypeScript port @yarmu/json-repair, or jsonmend, whose Python and JS versions pass the same 485-case conformance corpus. Otherwise the same output repairs to A on the client and B on the server, and debugging becomes miserable.
  • Turn on repair logging. @yarmu/json-repair with logging: true returns an array of every repair operation. A sudden spike in repair counts usually means your prompt or model version changed — an earlier signal than any error report.

One step after repair is non-negotiable: schema validation. Syntactically valid does not mean usable. Missing fields, wrong types, and unexpected keys are all caught by a schema. The contract-testing approach applies directly here; see our guide on JSON Schema contract testing.

Six: Prevention Checklist — the Cheapest Repair Is the One You Never Need

Repair is the fallback. Producing less broken JSON at the source is the real win, in priority order:

  1. Structured Outputs (json_schema mode). Decoding is constrained by the schema, so a trailing comma simply cannot be generated. OpenAI's strict mode fails at roughly 0.1%, at the cost of hard requirements such as additionalProperties: false.
  2. JSON mode (json_object). Guarantees syntactic validity only — not shape — and token-limit truncation still happens.
  3. Explicit instructions. On endpoints without JSON mode, spelling out "no fences, no comments, no trailing commas, output only the object" cuts error rates by 70-80%.
  4. Lower temperature, raise the token limit. The first reduces drifting into prose; the second reduces truncation.
  5. Retry with the error attached. When validation fails, append the broken output plus the "JSON path + error message" to the conversation and ask again. Models usually self-correct given precise errors.

In practice, layering "structured outputs + repair fallback + schema validation" covers virtually every scenario.

Seven: Dividing the Work — Dialect Conversion Is Not Repair

Within this site's toolbox, two destinations cover distinct segments of this pipeline:

  • Dialect problems (comments, single quotes, trailing commas) go straight to the JSON5 converter. JSON5 ↔ standard JSON conversion covers exactly these three classes with explicit, non-guessing semantics. If the whole input is a JSONC/JSON5 file, conversion is more predictable than repair. For the trade-offs of the dialects themselves, see the JSON5 and JSONC guide.
  • After repair, run the result through the JSON parser to validate and format it, with errors located to row and column, confirming a strict parser truly accepts the output.
  • Library-class problems (Python literals, truncation completion, JSONP wrappers, markdown fences) currently require code-side jsonrepair / json-repair — there is no equivalent one-click browser repair, because these repairs involve inferring intent, and a local library is a safer home for that than a general-purpose converter.

If what you are holding is an error message rather than broken data, start with the JSON parse error fix guide to translate the message into coordinates before deciding whether to edit by hand or repair.

FAQ

Will JSON repair corrupt my data?

For the nine repairable classes, only punctuation and wrappers change — values are untouched, and //, commas, and braces inside strings are preserved by the state machine. But truncation completion yields incomplete objects, leading-zero numbers become strings, and NaN handling varies by library. Reviewing key fields after repair is mandatory.

What is the relationship between repair and validation?

Validation tells you where the input is illegal; repair hands you a legal document. The reliable workflow does both: repair first, then validate — schema checks for types and required fields, syntax checks to confirm a strict parser accepts the result. Repairing without validating swaps a loud syntax error for a quiet data error.

The LLM always wraps output in a ```json fence — what do I do?

Short term, extract: take the text from the first { or [ to the last } or ] and parse that; a repairer with fence stripping will also consume the whole message. Long term, use structured outputs or an explicit "no markdown fences" instruction so the fence is never generated.

jsonrepair or json-repair — which one?

For JavaScript use the npm jsonrepair package (it supports a streaming transform); for Python use json-repair from PyPI. If both ends repair, pick a semantically aligned pair — json-repair plus its TS port, for example — so the same input repairs identically on both sides.

Can repairers handle CJK text and curly quotes?

Yes. Typographic quotes produced by CJK input methods (“”), full-width spaces, and a BOM at the start of the file are all on the standard repair list; curly quotes are normalized to straight ones. Run the result through a validator once and you are done.