Contents
- The Short Answer
- The 5 Causes at a Glance
- Cause 1: The AI Agent Answered in Prose
- Cause 2: The JSON Does Not Match the Schema
- Cause 3: Your Schema Has a Top-Level Field Called output
- Cause 4: Code Fences Inside the JSON (Before n8n 2.3.0)
- Cause 5: The Model Ran Out of Tokens
- What Auto-Fix, Retries and On Error Do
- Still Broken? Check These in Order
- How to Stop It Coming Back
- Sources
- FAQ
The Short Answer
The full error reads:
Model output doesn't fit required format
To continue the execution when this happens, change the 'On Error' parameter in the root node's settings
Both lines come from langchainParserError.ts. The parser throws it in two cases: the model's text is not valid JSON, or it is valid JSON that fails your schema. The source records which one as Invalid JSON in model output or Model output does not match the expected schema.
First check: open the failed execution and select the Structured Output Parser sub-node in the log. Its input has a text field: exactly what the model returned. Read it, then find your case below.
The 5 Causes at a Glance
| Symptom in the parser's text | Cause | Fix | How to confirm |
|---|---|---|---|
| A sentence, or JSON with prose around it | The agent answered without using its formatting tool | Parse in a Basic LLM Chain after the agent | Root node is an AI Agent; text does not start with { |
| Valid JSON, one field absent or the wrong type | Schema mismatch, often every field required | Write the schema by hand with a required list | Compare the keys in the text with the schema |
JSON whose only top-level key is output | Your schema uses a field named output | Rename that field | Search the schema for a top-level "output" |
| JSON with triple backticks inside a string value | Fence-splitting bug before n8n 2.3.0 | Update to 2.3.0 or later | Check your version in the About n8n panel |
Empty, {} or cut off mid-object | The model ran out of output tokens | Raise max tokens, shrink the prompt or schema | On 2.15.0 or later n8n shows a different, empty-response message |
Cause 1: The AI Agent Answered in Prose
When you turn on Require Specific Output Format on an AI Agent and attach a Structured Output Parser, n8n does not just add an instruction. The Tools Agent docs say the agent "passes the parser to the model as a formatting tool". In the source (ToolsAgent/common.ts) that tool is named format_final_json_response, and the model is told to call it with its final answer.
The model decides whether to call it, like any tool. When it answers in plain text instead, n8n parses that text, and a sentence is not JSON. That is why the error is intermittent.
How to confirm it: the root node is an AI Agent and the parser's text is a sentence or JSON with prose before it.
The fix: n8n's Structured Output Parser common issues page says parsing is often unreliable with agents and recommends passing the agent's output to a separate LLM Chain node to parse. In the main forum thread, the replies reporting stable results did the same.
- On the AI Agent, turn off Require Specific Output Format and remove the parser.
- Add a Basic LLM Chain node after the agent, with its own chat model.
- Set its prompt to Define below and pass the agent's answer in:
Extract the fields from this answer. Return only JSON.
{{ $json.output }}
- Turn on Require Specific Output Format on the chain and attach the Structured Output Parser there.
The agent keeps its tools; the chain only formats, and a small model is usually enough. For structure in an intermediate step, the docs say to describe it in the agent's System Message instead. See system prompt.
Cause 2: The JSON Does Not Match the Schema
The model returned valid JSON, but a field is missing, renamed, or the wrong type, such as "42" where the schema says number.
The most common trigger is the Generate From JSON Example schema type. The node docs say n8n treats every field in the example as mandatory. That started with node version 1.3, released in n8n 1.98.0. If the example has a phone field and the input has no phone number, the model leaves it out and the parse fails. A parser added before 1.98.0 keeps its older behaviour, so two copies of a workflow can differ.
How to confirm it: the parser's text is clean JSON. Compare its keys and value types with your schema field by field.
The fix: switch Schema Type to Define using JSON Schema and list only the fields you truly need in required:
{
"type": "object",
"properties": {
"name": { "type": "string" },
"email": { "type": "string" },
"phone": { "type": "string" },
"score": { "type": "number", "description": "0 to 100" }
},
"required": ["name", "score"]
}
Also from the docs: n8n does not support $ref in JSON schemas, so write nested objects out in full. And keep the schema small.
Cause 3: Your Schema Has a Top-Level Field Called output
Since parser version 1.3, n8n wraps your schema in an output key: the parser expects { "output": { ...your fields } }. When an agent's final answer is JSON, the source checks whether it already has that shape. If the JSON's only top-level key is output, n8n assumes it is already wrapped and does not wrap it again.
So a schema like this one breaks:
{ "output": "The customer wants a refund" }
n8n treats your field as the wrapper, and the string fails the object check. A reply in the main forum thread traced a failure to this parent output key.
How to confirm it: your schema or JSON example has a top-level property named output.
The fix: rename it to something else, such as answer or summary, and update any later nodes that read it.
Cause 4: Code Fences Inside the JSON (Before n8n 2.3.0)
The parser removes an outer markdown fence before parsing. GitHub issue #21174 showed that older versions split the text on the first triple backtick they found anywhere, including inside a string value.
The fix shipped in n8n 2.3.0 (pull request #23726). The parser now only treats backticks on their own line as a fence.
How to confirm it: you are on a version before 2.3.0 and the parser's text contains ``` inside a value.
The fix: update n8n. If you cannot update yet, add a line like this to the system message, which is what forum users did before the fix:
Return raw JSON only. Do not wrap the response in markdown code fences.
Do not use triple backticks inside any string value.Cause 5: The Model Ran Out of Tokens
If the reply is empty, {}, or stops halfway through an object, the model hit its output limit before it finished. Reasoning models are prone to this: the source notes that a thinking model's finish with only thinking content becomes an empty output.
Since n8n 2.15.0 this case has its own message: "The AI model returned an empty response to the Structured Output Parser",. On earlier versions it shows "Model output doesn't fit required format", which hides the real cause.
How to confirm it: the parser's text is empty or truncated.
The fix: raise Maximum Number of Tokens in the chat model sub-node's options, send less input, or split the schema across two calls. If one model keeps failing, try another for this step: issue #18765 reports Gemini 2.5 Flash working where 2.5 Pro failed on the same parser.
What Auto-Fix, Retries and On Error Do
Auto-Fix Format. An option on the Structured Output Parser since n8n 1.98.0. When on, the parser gets a Model connector, and a failed parse triggers another model call that is shown the schema, the bad output and the error, and asked to correct it. The separate Auto-fixing Output Parser node does the same job. It helps but does not guarantee success: the original poster in the main forum thread had auto-fix and retries on and still saw the error.
Retry On Fail and On Error. Retry On Fail reruns the whole call at full cost. On Error, which the error text points to, lets the workflow continue; use its error output to route failures to a person, not to hide them. See error handling.
A fix that does not work. Several forum replies suggest renaming the parser node to format_final_json_response. The tool name is hard-coded in n8n's source and the parser node's name is not sent to the model, so renaming changes nothing.
Still Broken? Check These in Order
- Read the parser's
textin the execution log. - Check your version in the About n8n panel. Before 2.3.0 the fence bug applies. Before 2.15.0 an empty reply shows this message.
- Paste the
textinto a JSON validator. If it fails, it is Cause 1, 4 or 5. If it passes, it is Cause 2 or 3. - Test the same prompt in a Basic LLM Chain with the parser. If the chain passes and the agent fails, it is Cause 1.
- Remove schema fields until it passes, then add them back one at a time.
How to Stop It Coming Back
Split reasoning from formatting. Agent first, then a Basic LLM Chain with the parser. This one change removes the most common cause.
Write the schema by hand for production. A JSON example is fine for a prototype.
Route failures to a review step instead of dropping them.
Keep n8n current. Two of the five causes are fixed bugs.
How the agent hands its answer to a parser is covered in our free lesson on the AI Agent node. See also tool calling, contents.parts must not be empty if you use Gemini, and A Chat Model sub-node must be connected.
The n8n AI Agents course builds working agents end to end: tools, memory, structured output, RAG, error handling with human fallback, and deployment, with importable workflow JSON for every lesson.
Sources
Checked against n8n's documentation, source code, release notes and community forum on 17 November 2026.
- n8n docs: Structured Output Parser common issues - the LLM Chain recommendation.
- n8n docs: Structured Output Parser - schema types and
$ref. - n8n docs: Tools Agent - the parser passed as a tool.
- n8n source: N8nStructuredOutputParser.ts - fences, the output wrapper, empty replies.
- GitHub issue #21174 - the code fence bug, fixed in n8n 2.3.0.
- n8n community: Model output doesn't fit required format - Structured Output Parser
FAQ
- What does "Model output doesn't fit required format" mean in n8n?
- The Structured Output Parser could not use the model's reply. Either the reply was not valid JSON, or it was valid JSON that did not match the schema you set, for example a required field was missing or had the wrong type.
- Why does the error only happen sometimes?
- Model output varies from run to run. With an AI Agent, the model chooses whether to call the formatting tool, and some runs it answers in plain text instead. Moving the parser to a Basic LLM Chain after the agent makes the formatting step far more consistent.
- Should I use the Structured Output Parser on the AI Agent or on an LLM Chain?
- n8n's own docs say parsing is often unreliable with agents and recommend passing the agent's output to a separate LLM Chain node for parsing. Use the agent for reasoning and tools, and the chain for the final JSON.
- Does Auto-Fix Format solve the error?
- It reduces it. Auto-Fix Format, added to the Structured Output Parser in n8n 1.98.0, sends a failed reply back to a model with the schema and the error and asks for a corrected version. It costs an extra model call and can still fail.
- Why does my schema from a JSON example fail when a field is empty?
- Since Structured Output Parser version 1.3, every field generated from a JSON example is required. Define the schema with JSON Schema and list only the fields you need under required.
- Does renaming the parser to format_final_json_response help?
- No. format_final_json_response is the name of the tool the AI Agent gives the model, and it is hard-coded in n8n's source. The parser node's own name is not sent to the model, so renaming the node has no effect.
If this resonated
Module 02 is the long version of this post.
Eval set, refusal pattern, kill switch. Build it in a weekend.
