By AI Promix Editorial Team · Documentation and issue status checked:
To fix n8n’s “Model output doesn't fit required format” error, first check the Structured Output Parser’s mode and compare the response with its schema. The message means structured-output processing failed; it does not identify a single cause. Configuration mismatches, malformed responses, agent behavior, and specific software defects need different checks.
Quick answer: Confirm the parser mode, check the response’s fields and types, then isolate the failing configuration with a small test. Investigate version-specific bugs only when the symptoms match.
Check three different things: JSON syntax determines whether the response can be read as JSON. Schema validation checks its shape and values. Business validation checks whether the content is correct for the task. A structured parser must read and validate the response; it does not prove that a summary or classification is accurate.
Find the failing step before changing the model
Start with the failed execution and record:
- The node reporting the error and its attached output parser.
- The selected parser mode and the exact schema or example.
- Your n8n version, model/provider, and relevant model settings.
Inspect the input, response, and error details available in your execution view. If the raw model response is unavailable, reproduce the problem in a diagnostic copy. Preserve the original input and change one setting at a time. Interface labels and available execution details can vary by version.
Check the parser mode: JSON Example vs. JSON Schema
Check Schema Type before editing the prompt. The Structured Output Parser documentation distinguishes two modes:
-
Generate from JSON Example infers keys and types from a
sample object you paste in. It ignores the actual example values (an
example value of
"high"does not restrict future results tohigh), and it treats every inferred field as mandatory. - Define using JSON Schema takes an explicit schema, where you control which properties are required and which are optional, and what types and enum values are allowed.
Pasting a schema into example mode makes the parser infer the schema
document’s own keys, such as type and properties,
instead of your intended output. The documentation also states that
$ref references are unsupported.
For dynamic schemas, also check expressions: in sub-nodes, they resolve against the first input item. Investigate this behavior if a later record appears to reuse the first record’s configuration.
If you are also reconsidering your workflow design, our n8n Agents vs AI Agent node comparison explains where output validation belongs in each approach, with published examples to help you choose.
| Symptom | Possible cause | Check |
|---|---|---|
| Parser rejects output that looks like your example | Example mode and schema mode confused, or a schema pasted into the example field | Confirm which mode is selected and that the field contains the matching format |
| Response is incomplete or cannot be read as JSON | Malformed JSON or content outside the requested object | Inspect the full response for missing delimiters, trailing commas, or extra prose; simplify the task and request one complete object |
| Output is valid JSON but still fails | Missing required field, wrong type, or a value outside an enum |
Compare the raw response field-by-field against your schema's
required, type, and enum
|
| Error only appears when using an AI Agent | Direct agent parsing is a candidate for isolation | Test the agent’s final result in a separate formatting chain |
| JSON contains triple backticks / Markdown inside a string | Possible match to issue #21174 on n8n 1.116.2 | Compare the exact symptom with the historical fix notes |
Auto-Fix Format fails with typed content turned into
[object Object]
|
Possible match to issue #38016 (Responses API repair model, n8n 2.28.0) | Check the dated report and proposed fix for a matching configuration |
Check the response against the schema
For Generate from JSON Example, paste an output object like this:
{
"summary": "Report export is blocking a client delivery.",
"priority": "high",
"needs_review": true
}For Define using JSON Schema, paste this schema instead:
{
"type": "object",
"properties": {
"summary": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"low",
"normal",
"high"
]
},
"needs_review": {
"type": "boolean"
}
},
"required": [
"summary",
"priority",
"needs_review"
]
}
This small schema requires three fields and restricts
priority to three values. It does not prohibit additional
properties. Check your installed parser’s returned data before relying on it
to preserve or reject extra fields.
The
JSON Schema object reference
explains that required controls which listed properties must
exist. Omitting that keyword does not make a schema invalid or disable its
other constraints. A present null value must still satisfy the
field’s schema, including its type and any allowed-value restrictions.
Here are three variants that are all syntactically valid JSON but each fail the schema above for a different reason:
Missing a required field
{
"summary": "Report export is blocking a client delivery.",
"priority": "high"
}needs_review is required and absent.
Wrong type
{
"summary": "Report export is blocking a client delivery.",
"priority": "high",
"needs_review": "true"
}
needs_review is the string "true", not the boolean
true.
Value outside the allowed enum
{
"summary": "Report export is blocking a client delivery.",
"priority": "urgent",
"needs_review": true
}
"urgent" isn't one of the allowed priority values.
Handle missing information explicitly. Make a property
optional, or allow null, only when that matches the intended
data contract and your implementation supports it. Do not invent a value
merely to pass validation.
Build a minimal chain to isolate the problem
Use a small, known input to separate parser configuration from the complexity of your original workflow.
Prerequisites
- A disposable copy of the workflow
- An available Basic LLM Chain node
- A compatible Chat Model with working credentials. If you use OpenRouter, see connect OpenRouter to n8n.
- Destination actions disconnected while you test
Steps:
- Add a Basic LLM Chain to the diagnostic workflow and attach your configured Chat Model.
- Set Prompt to Define below and paste the copyable prompt below into Prompt (User Message). These are the labels in the current documentation; your version may differ.
- Enable Require Specific Output Format. Add a Structured Output Parser through the parser attachment, select Define using JSON Schema, and paste the schema above.
- Run the chain. Compare its response with both the schema and the ticket before reconnecting destination actions.
- If the small case succeeds, restore the original input, schema, and agent configuration one change at a time. Record which change reproduces the failure.
See the Basic LLM Chain documentation for its prompt and parser settings.
Summarize and classify the support ticket below.
Return one JSON object matching the attached schema.
summary: one sentence based only on the ticket.
priority: high when the ticket explicitly says a task is blocked;
low for a non-urgent suggestion; otherwise normal.
needs_review: true when the ticket asks for investigation or
intervention; otherwise false.
Use the exact allowed priority values and JSON booleans.
Do not add commentary or wrap the response in a Markdown code block.
Do not invent a cause, diagnosis, or completed action.
Ticket:
Report export fails and is blocking today's client delivery.
Please investigate.Illustrative expected result: Check the required fields and the ticket’s meaning; an exact summary-text match is unnecessary.
{
"summary": "Report export is failing and blocking a client delivery.",
"priority": "high",
"needs_review": true
}When an agent needs a separate formatting chain
For tool-using workflows, n8n recommends a separate LLM chain to parse the agent’s final result. Its documentation notes reliability concerns with direct agent parsing. The Structured Output Parser targets the agent’s final output, not intermediate tool output.
If the task only requires extraction or classification, start with a Basic LLM Chain. The parser attaches through Require Specific Output Format; it is a sub-node connected to the root, rather than a regular step on the main data path.
Direct extraction or classification
- Input
- Basic LLM Chain
- Check business rules
- Destination
Task that needs an agent and tools
- Input
- AI Agent
- Formatting chain
- Check business rules
- Destination
A downstream check only receives successful output. If parsing prevents the chain from returning data, handle that failure through the root node’s error path or a workflow-level error handler. A later validation node cannot catch data it never receives.
For ticket triage, also compare the summary and priority with the source
ticket. A valid needs_review boolean does not prove the model
made the right review decision.
Check historical and reported defects
After configuration checks, compare your symptoms and version with a specific report. The following cases concern different failure paths.
Markdown inside a JSON string (n8n 1.116.2)
Issue #21174 reported triple backticks inside a JSON string causing trouble on n8n 1.116.2. The 2.3.0 release notes list the fix from PR #23726 on January 5, 2026. That page is marked pre-release. Use it to identify the historical fix; select an appropriate supported release for your deployment rather than installing this old version just because it is named here.
Auto-Fix Format with the Responses API (n8n 2.28.0)
Issue #38016
reports a reproduction on n8n 2.28.0: when the auto-fix repair model uses
the Responses API, typed message blocks can become
[object Object] instead of repaired JSON. The report and
proposed
PR #33184
were open when checked on September 20, 2026; no released fix was verified.
Compare the report’s configuration with yours and recheck its status before
choosing a workaround.
Handle failures and verify business rules
Choose how failures should be handled before reconnecting the workflow to its destination.
Auto-fixing makes an additional model call to attempt repair after parsing fails, as described in the Auto-fixing Output Parser documentation. Repair may add model usage and latency, and can fail again. Correct the schema and prompt first; keep retries bounded. Do not strip Markdown indiscriminately from legitimate string values.
In the executing root node’s On Error settings, Continue (using error output) provides a path for error information. Where this option is available, connect that path to handling such as recording the failure and routing it for review. Test that it receives the intended data.
Plain Continue uses the last valid data and does not establish that the model response passed validation. An error handled within the workflow also does not necessarily fail the whole execution, so do not assume it will trigger the separate error workflow.
For workflow-level handling, create a separate workflow starting with Error Trigger and select it in the main workflow’s Error workflow setting. It responds to failed automatic executions; manual test runs do not trigger it. See n8n’s error-workflow setup.
If your workflow fails but the error handler does not run, follow our guide to fix an n8n Error Trigger that is not working. It covers execution mode, handler settings, and a controlled test to verify the alert path.
Before reconnecting a fixed chain to real destinations, check:
- Can you tell which parser mode accepts each of your test payloads?
- Does the returned object satisfy the schema, and is its content still faithful to the source ticket?
- Does a deliberately broken test case actually reach your chosen error path, instead of the normal destination?
- If you rely on a workflow-level error handler, have you tested it through an actual automatic execution?
- Does restoring one specific original component reproduce the original failure?
A passing isolated example is a starting point. Repeat the checks with representative inputs, including missing information and cases that previously failed.
Frequently asked questions
Why does valid JSON still fail the Structured Output Parser?
Because the parser checks more than syntax. Valid JSON can still be missing a required field, use the wrong type, or contain a value outside an allowed enum — all of which are schema failures, not JSON errors.
Does every JSON Schema need a required array?
No. In an object schema, required specifies keys that
must be present. Omitting it does not disable type checks or other
constraints. If a required key contains null, that value
must still be allowed by the field’s complete schema.
Should I use an AI Agent or a Basic LLM Chain?
Start with a Basic LLM Chain for a single extraction or classification task. Use an agent when it needs to select tools or take intermediate actions; follow n8n’s separate-chain recommendation when formatting its final response.
Will Auto-Fix Format always solve the error?
No. It's an additional repair attempt using another LLM call, not a substitute for a correct schema, and it can add cost and latency. Fix the underlying schema or prompt first.
Why did my Error Trigger not run during a manual test?
Error Trigger workflows respond to automatic execution failures. Manual test runs don't trigger it — test error workflows through an actual automatic execution instead.
Which n8n version fixes this error?
No version fixes every cause of this message. Configuration errors need configuration changes; a software fix applies to a particular defect. Match your symptoms to the issue and its release notes.
Practical next step and sources
Run the minimal example in a diagnostic copy, inspect the response against the schema, and restore your original configuration one change at a time. Reconnect destination actions only after checking both successful output and the intended failure path.
Research method: This guide draws on official n8n documentation, release notes, and attributed repository reports checked on September 20, 2026. The examples were checked for JSON syntax but were not executed in n8n. They illustrate the method rather than document a hands-on benchmark.