What does 'Model output doesn't fit required format' mean in n8n?

It means the Structured Output Parser received a reply from the model that it couldn't validate against your schema. The reply was prose instead of JSON, JSON wrapped in markdown fences, malformed JSON, or valid JSON with a missing field or wrong type, such as null where the schema expects a string.

Why does n8n's Structured Output Parser fail with 'Unexpected token'?

The model started its reply with text instead of JSON, for example 'I'll help you with that', so the JSON parser hit a letter where it expected a brace. Tell the model to return only a JSON object with no preamble and no code fences, and put that instruction at the end of the system message.

Should I turn on Auto-Fix Format in the Structured Output Parser?

Turn it on for low-stakes generation like ad copy or image prompts, where a second model call that repairs the format is cheap and harmless. Leave it off for data that writes to a CRM, a calendar or a billing system. There you want the run to fail loudly, not have a second model quietly invent a field.

How do I fix 'Failed to parse agent steps' on a Basic LLM Chain in n8n?

If the model output looks valid and you're getting this error on a Basic LLM Chain with a Structured Output Parser, check your n8n version first. A community write-up traces it to a library double-load bug, tracked as n8n issue #29903, that was fixed in n8n 2.30.0. Upgrading cleared it.

Is the Basic LLM Chain more reliable than the AI Agent for structured output?

Usually, yes. The Basic LLM Chain makes one call and parses it. The AI Agent has to juggle tools, memory and the decision to stop before it formats anything. A reliable pattern is to let the agent do the work in plain text and hand its answer to a Basic LLM Chain whose only job is formatting.

n8n Structured Output Parser Errors: How to Fix Them

The n8n Structured Output Parser fails when the model's reply doesn't match the schema you gave it. "Model output doesn't fit required format" almost always means one of four things: the model wrote a sentence before the JSON, wrapped it in markdown fences, returned null or the wrong type for a field, or skipped a field your schema marks as required. Fix it in this order: read the raw model output, rule out the 2.30.0 version bug, replace "Generate from JSON Example" with a real JSON Schema, and if an AI Agent with tools keeps failing, move the formatting into a separate Basic LLM Chain.

That last move fixes more broken workflows than any prompt tweak. Here's why, and what we look at first when a client's agent starts throwing parser errors.

What does "Model output doesn't fit required format" actually mean?

The Structured Output Parser is a validator sitting between the model and the rest of your workflow. It takes the model's text, tries to parse it as JSON, then checks it against your schema. If either step fails, the node errors and nothing downstream runs.

The model isn't "broken" when this happens. It did what language models do: it wrote text. The parser is the thing that insists the text be a very specific shape. So the question is never "why is n8n failing?" It's "what did the model actually send?"

Open the failed execution, click the chat model sub-node, and read the raw response before you change anything. Nine times out of ten the problem is visible in the first line.

Which parser error do you have?

The error text tells you a lot about the cause. These are the three we see most:

"Model output doesn't fit required format": the output parsed, or almost parsed, but failed the schema. Usually a missing key, null where a string was expected, a number sent as "12", or an extra wrapper object.
"Unexpected token 'I', "I'll help"... is not valid JSON": the model opened with prose. This is the classic one on the AI Agent node, and it was reported against n8n issue #26004 with Claude Sonnet 4.5 and a few MCP tools attached.
"Failed to parse agent steps" on a Basic LLM Chain: this one can be a bug, not your prompt. More on it below.

If you get the first error intermittently, say 1 run in 20, it's almost always the schema. If you get the second, it's the prompt or the agent setup. If you get the third and the output looks perfect, check your version.

Is it a bug in your n8n version?

Sometimes, yes. A community write-up from August 2026 traced "Failed to parse agent steps" on a Basic LLM Chain plus Structured Output Parser to a library double-load inside n8n: two copies of @langchain/core broke an internal type check, so the chain's output got routed through agent parsing logic. It's tracked as issue #29903, and the author reports it was fixed in n8n 2.30.0 (July 2026), with a backport to the 2.29.4 beta. Upgrading cleared it immediately.

If the raw output is valid JSON that matches your schema and the node still fails, upgrade before you rewrite a single prompt. We've watched people spend an afternoon "fixing" a schema that was never wrong.

If you self-host, test the upgrade on a copy first. We cover how in our guide to rolling back a self-hosted n8n upgrade.

Why does "Generate from JSON Example" cause so many failures?

This is the root cause behind most intermittent failures we fix, and it's the default.

When you pick Generate from JSON Example, n8n builds a schema from your sample object. It reads property names and types and ignores the values. The official docs are explicit about the catch: n8n treats every field as mandatory when it generates a schema from an example.

That causes three predictable problems:

Every field is required. If your example has "company": "Acme" and the caller never said a company name, the model either invents one or leaves it out. Leaving it out fails validation.
Types get locked from your sample. Write "budget": "" and budget is a string forever. The model returns null for an unknown budget, and the run fails.
Empty arrays tell the schema nothing useful. "services": [] gives the model no idea what goes inside.

When we audited our own n8n instance this week, we found 21 Structured Output Parser nodes across 13 workflows, and every one of them used Generate from JSON Example. The ones that broke most often were the wide, flat schemas: call-summary parsers on inbound voice agents with 7 to 10 fields each, where real callers routinely skip half the information.

The fix is to switch to "Define using JSON Schema" and be honest about what's optional. A minimal version for a call summary looks like this:

{
  "type": "object",
  "properties": {
    "caller_name": { "type": ["string", "null"] },
    "intent": { "type": "string", "enum": ["booking", "quote", "support", "other"] },
    "callback_number": { "type": ["string", "null"] },
    "summary": { "type": "string" }
  },
  "required": ["intent", "summary"],
  "additionalProperties": false
}

Two rules from the docs to remember: the parser doesn't support $ref, so inline every definition, and enums do more for reliability than any instruction you write. The model can't invent a fifth intent when the schema only allows four.

Why does the AI Agent node fail more than the Basic LLM Chain?

The Basic LLM Chain makes one call and parses the answer. Simple.

The AI Agent has a harder job. It reads memory, decides whether to call tools, calls them, reads the results, decides it's done, and only then has to produce your exact format. Every tool result and every earlier chat turn pulls the model toward conversational replies. Attach memory where previous turns were plain text, and the model has a whole history of "talking normally" to imitate.

That's why the "I'll help you with that" preamble shows up almost exclusively on agents with tools.

Our default pattern: let the agent think, let a chain format. Remove the parser from the agent, let it answer in plain text, and pass its output into a Basic LLM Chain with the Structured Output Parser and a short prompt like "Extract these fields from the text below." You pay for one extra small-model call. In exchange, the agent's tool loop stays clean and the formatting step becomes almost boring.

This pairs well with the other agent fixes we've written up, like stopping an agent that hits max iterations in a loop or one that calls the wrong tool. Most of them come down to giving each node one job.

How do you write the prompt so the model returns only JSON?

Prompting won't save a bad schema, but it does stop the preamble problem. What works for us:

Put the format rule last in the system message, after the task instructions. Models weight the end of the prompt heavily.
Say what not to do. "Return only one JSON object. No text before or after it. No markdown code fences."
Tell it what to do with missing data. "Use null for any value the input doesn't contain. Never guess." This one line kills most of the invented-field problems.
Lower the temperature on the formatting call. Creativity is not what you want from a parser step.
Keep the schema small. If you need 25 fields, split the extraction into two calls. Long schemas fail more, and they fail in harder-to-debug ways.

Should you turn on Auto-Fix Format?

The Structured Output Parser has an Auto-Fix Format option, and there's also a separate Auto-fixing Output Parser node that wraps another parser. Either way, when parsing fails, n8n sends the bad output and the error back to a model and asks it to repair the format. You pay for that extra call every time it triggers.

In our instance, 12 of the 21 parser nodes have Auto-Fix on. All 12 sit in creative workflows (ad scripts, image prompts, video storyboards) with one-key schemas. None of the call-summary parsers on our voice agents use it.

That split is the one we'd recommend: auto-fix where a repaired format is harmless, fail loudly where the data feeds a CRM, a calendar or an invoice. A second model "fixing" a missing callback number may well fill it with something plausible and wrong. For an image prompt, who cares. For a lead record, you'd rather get an alert.

How do you stop one bad response from killing the whole run?

Even with a good schema, an occasional failure will happen. Plan for it instead of hoping:

Open the AI Agent or Basic LLM Chain node settings and set On Error to continue using the error output.
Route the error branch to a retry, ideally with a stricter prompt or a stronger model, capped at one or two attempts.
If the retry fails too, send the raw model output, the error and the input to your error workflow so a human sees it.

We go deeper on alerting in our guide to n8n error handling and monitoring. And before any agent goes live, run it against a batch of messy real inputs, not your three clean test cases. Our checklist for testing n8n AI agents before production covers how we build that batch.

The quick checklist

If you're staring at a parser error right now, work through it in this order:

Read the raw model output in the failed execution before changing anything.
Check your n8n version if the output looks valid. "Failed to parse agent steps" on a Basic LLM Chain was a bug fixed in 2.30.0.
Replace Generate from JSON Example with a real JSON Schema: nullable types, enums, only truly required fields, no $ref.
End the system message with a strict "JSON only, no fences, null for unknowns" rule.
Split the agent from the formatter if tools or memory keep producing prose.
Use Auto-Fix Format only where a repaired value can't hurt anyone.
Catch failures with the error output and log the raw response.

Get a free automation audit

If your n8n agents work in testing and break on real customer data, the problem is usually in a few predictable places: loose schemas, agents doing too many jobs, and no error path. We've built and repaired a lot of these for clients across voice AI, lead routing and content pipelines.

Get a Free Automation Audit and we'll review your workflows, point out what's likely to break, and show you how we'd fix it. If you'd rather hand the whole thing off, see our n8n workflow automation service.