Skip to content
Agent Month
Email

How to fix: model returned invalid / unparseable JSON

Last verified: June 2026· Extraction and tool-use pipelines

Where this shows up

Extraction and tool-use pipelines

The fix

  1. 1Use structured outputs (schema-enforced JSON) if your provider/model supports it — this guarantees parseable output at generation time.
  2. 2For tools, enable strict tool use so arguments validate against your schema.
  3. 3Stop prefilling the assistant turn to force JSON — modern models reject prefills; use the schema parameter instead.
  4. 4Always parse with a real JSON parser and handle failure by retrying with a clarifying instruction, not by string-patching the output.
  5. 5Validate the parsed object against your schema and surface mismatches as errors the model can correct.

Prevent it

Adopt structured outputs everywhere you consume model output programmatically, and cover the route with an eval so regressions are caught.

Common variations and related errors

You'll usually hit this same root cause under a few different names. Same fix.

  • "Invalid JSON"
  • "JSON parse error"
  • "expected property name"
  • "model returned malformed JSON"
  • "function call arguments invalid"
  • openai.InvalidJSONOutput
  • "tool_use_failed"

Code: drop-in retry helper

A minimal typescript helper that handles the most common version of this error. Copy, paste, adjust the policy to your traffic.

// Always request structured outputs (schema-enforced) for JSON routes.
// If you can't, retry with a clarifying instruction and surface the error.
import OpenAI from 'openai';
const client = new OpenAI();

async function extractOrder(text: string) {
  const schema = {
    type: 'object',
    properties: { orderId: { type: 'string' }, total: { type: 'number' } },
    required: ['orderId', 'total'],
    additionalProperties: false,
  } as const;
  const res = await client.responses.create({
    model: 'gpt-4o-mini',
    input: text,
    text: { format: { type: 'json_schema', name: 'order', schema, strict: true } },
  });
  return JSON.parse(res.output_text);
}

Frequently asked questions

What causes “model returned invalid / unparseable JSON”?

The model produced free-form text or slightly malformed JSON instead of strictly valid, schema-conforming output.

How do I prevent “model returned invalid / unparseable JSON” from recurring?

Adopt structured outputs everywhere you consume model output programmatically, and cover the route with an eval so regressions are caught.