Short answer
Why Is My AI Step Returning Invalid JSON?
An AI step returns invalid JSON when the prompt allows prose or Markdown, the model invents keys, output is truncated, or unescaped characters break parsing. Use schema-constrained output when available, request only the required fields, validate before downstream actions, and route invalid responses for repair or review.
Common causes
- The response includes code fences, commentary, or a leading label.
- Keys, types, or enum values are not constrained.
- A long response is truncated before closing brackets or braces.
- Quotes, newlines, or backslashes inside generated text are not escaped correctly.
Diagnostic steps
- Define the smallest required schema with names, types, allowed values, and nullable fields.
- Use the platform’s structured-output feature rather than prompt-only formatting when available.
- Parse and validate the response before any customer-facing or destructive action.
- Retry or repair invalid output with a limit, then send persistent failures to human review.
Example
A model wraps an otherwise valid object in a Markdown code fence. Schema output or a validation step prevents the parser from receiving those extra characters.
Caveats
JSON syntax validation does not prove factual accuracy or safe business judgment. Keep high-impact decisions gated even when the shape is valid.