A8gent
All articles

Technical

Model output doesn't fit required format: 5 Causes and the Fix for Each in n8n

The Structured Output Parser could not turn the model's reply into JSON that matches your schema. Usually an AI Agent answered in prose instead of JSON, or the reply left out a field the schema requires. Here is how to tell which, and the fix for each.

A8gentAutomation practiceNovember 17, 202610 min read

Short answer: "Model output doesn't fit required format" means n8n's Structured Output Parser could not parse the model's reply against your schema. The most common cause is an AI Agent answering in plain text instead of JSON. The fix n8n's docs recommend: turn off Require Specific Output Format on the agent, add a Basic LLM Chain after it with the Structured Output Parser attached, and let the chain do the formatting.

Contents
  1. The Short Answer
  2. The 5 Causes at a Glance
  3. Cause 1: The AI Agent Answered in Prose
  4. Cause 2: The JSON Does Not Match the Schema
  5. Cause 3: Your Schema Has a Top-Level Field Called output
  6. Cause 4: Code Fences Inside the JSON (Before n8n 2.3.0)
  7. Cause 5: The Model Ran Out of Tokens
  8. What Auto-Fix, Retries and On Error Do
  9. Still Broken? Check These in Order
  10. How to Stop It Coming Back
  11. Sources
  12. 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 textCauseFixHow to confirm
A sentence, or JSON with prose around itThe agent answered without using its formatting toolParse in a Basic LLM Chain after the agentRoot node is an AI Agent; text does not start with {
Valid JSON, one field absent or the wrong typeSchema mismatch, often every field requiredWrite the schema by hand with a required listCompare the keys in the text with the schema
JSON whose only top-level key is outputYour schema uses a field named outputRename that fieldSearch the schema for a top-level "output"
JSON with triple backticks inside a string valueFence-splitting bug before n8n 2.3.0Update to 2.3.0 or laterCheck your version in the About n8n panel
Empty, {} or cut off mid-objectThe model ran out of output tokensRaise max tokens, shrink the prompt or schemaOn 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.

  1. On the AI Agent, turn off Require Specific Output Format and remove the parser.
  2. Add a Basic LLM Chain node after the agent, with its own chat model.
  3. Set its prompt to Define below and pass the agent's answer in:
Extract the fields from this answer. Return only JSON.

{{ $json.output }}
  1. 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 text in 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 text into 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.

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.

All postsLast verified 2026-11-17

Done for you

Want this built for your business?

Tell us the workflow. We scope, build, and ship the agent with guardrails and the numbers to prove it worked. The scoping call is free.

Free scoping call. You own the code.

Request a scoping call