How to fix: model returned invalid / unparseable JSON
Cause
The model produced free-form text or slightly malformed JSON instead of strictly valid, schema-conforming output.
The fix
- 1Use structured outputs (schema-enforced JSON) if your provider/model supports it — this guarantees parseable output at generation time.
- 2For tools, enable strict tool use so arguments validate against your schema.
- 3Stop prefilling the assistant turn to force JSON — modern models reject prefills; use the schema parameter instead.
- 4Always parse with a real JSON parser and handle failure by retrying with a clarifying instruction, not by string-patching the output.
- 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.
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.