n8n Structured Output Parser Not Working? 5 Real Causes

The parser does four things, in order. It strips a markdown code fence if it finds one, runs JSON.parse, validates the result against your schema with Zod, and then unwraps the output key. Each step has its own way to fail, but the canvas shows you the same sentence for most of them. The real reason is stored in the error context as outputParserFailReason: "Invalid JSON in model output", "Model output does not match the expected schema", or "Model output wrapper is an empty object".

To see exactly where the line is, I loaded the parser class straight out of the n8nio/n8n:stable image (2.46.6) and gave it 17 outputs for a simple schema built from the JSON example {"company": "...", "score": 72, "tags": [...]}. Here are 15 of them:

The fence handling is narrower than people assume. It only strips a fence when the opening line is exactly ``` or ```json. An uppercase ```JSON, or a fence and the JSON on the same line, goes straight to JSON.parse and fails. Prose before bare JSON fails too, while the same prose before a fenced block works. Also note that every field from a JSON example is required in parser 1.3, so a model that skips tags or sends null fails validation.

This is the most misleading message in the node. Parser 1.3 wraps your schema in an output object, and the format instructions it injects tell the model to return {"output": {...}}. If the model sends back a correct object without that wrapper, Zod sees outputas undefined and n8n picks its "empty" message:

Input to the parser (valid JSON, right fields, no wrapper):
{"company":"Acme","score":72,"tags":["a"]}

Error: The AI model returned an empty response to the Structured Output Parser
"This usually happens when the model runs out of tokens before it can generate
the structured output. Try reducing the prompt length, increasing the model's
max output tokens, or simplifying the output schema..."

The JSON was fine. Nothing ran out of tokens.If you follow the advice in that message, you'll shorten your prompt and raise limits for nothing.

Where you hit this depends on the root node. The AI Agent has a step that catches a bare JSON object and wraps it in outputfor you before the parser sees it. The Basic LLM Chain doesn't. It pipes the model's text straight into the parser. I checked it with a stubbed model that always returned the bare object: Basic LLM Chain 0 of 10, AI Agent 10 of 10. Same text, opposite result. If your raw text looks right and the key is missing, either move that step to an agent or drop the parser and parse the text yourself in a Code node.

Less often than the forum threads suggest. I built a lead-scoring workflow (10 local businesses, each scored 0 to 100 with 2 to 4 tags) on the Google Gemini Chat Model with gemini-3.1-flash-lite, then tried to make it fail. I asked for a different JSON shape in my own prompt. I asked for the score as a percentage. I asked it to reason step by step before answering. I even told it to ignore the schema and reply in one sentence.

130 calls with a normal token budget, 130 parsed.That covers the Basic LLM Chain and the AI Agent. n8n adds its format instructions to every call (after your prompt in the chain, in the system message for the agent), and this model followed them every time over what my prompt said. I'm not claiming every model behaves this way. But it does mean the first thing to check isn't "the model is bad at JSON."

The one setting that broke it every time was the token limit. With Maximum Number of Tokensat 40, 10 of 10 items failed, and the Gemini sub-node's output said exactly why:

// Gemini sub-node output, Maximum Number of Tokens = 40
"text": "```json\n{\n  \"output\": {\n    \"company\": \"Acme Roofing\",\n    \"score\": 95,\n    \"tags\": [\n",
"finishReason": "MAX_TOKENS"

The parser error itself only said "doesn't fit required format." The finishReason is in the model sub-node, not the chain, which is why you have to click into it. 40 tokens is an extreme setting, but the same thing happens with a normal limit when a thinking model spends most of its budget reasoning, or when the schema asks for long arrays.

Auto-Fix Format adds a model input to the parser. When parsing fails, it makes exactly one extra call with this prompt, then parses the reply. If that fails too, you get the error. It doesn't loop.

Instructions:
--------------
{instructions}      <- the parser's format instructions
--------------
Completion:
--------------
{completion}        <- the broken output
--------------
Above, the Completion did not satisfy the constraints given in the Instructions.
Error:
--------------
{error}
--------------
Please try again. Please only respond with an answer that satisfies the
constraints laid out in the Instructions:

Look at what's missing: the original input.The fix model never sees the lead it's supposed to describe. I turned Auto-Fix on for the truncated 40-token run. Every item "succeeded": 10 of 10 valid, zero errors. Then I read the data.

Lead in                                    Auto-Fix result
Acme Roofing in Plano, TX. 4.6 stars...  -> "TechNova Solutions", 88.5, ["software","innovation","cloud"]
Joe's Mobile Detailing, McKinney...      -> "TechNova Solutions", 88.5, ["software","cloud","innovation"]
Bright Smile Dental, Frisco...           -> "Bright Smile Dental", 15, ["dentistry","healthcare","local"]

Two leads became a software company that doesn't exist, with an identical made-up score. The other eight kept the name and score from the truncated text, but all ten got tags the fix model invented without seeing the business. A roofing lead with no website came back tagged "cloud." It all passed validation, so nothing downstream would have caught it.

For extraction and scoring, Auto-Fix swaps a loud failure for quiet bad data. It's fine when the failure really is cosmetic and every value is already in the broken completion, like a trailing comma. If you do use it, add a check after the chain that the company name actually appears in the input. I wrote more about catching this kind of silent wrongness in n8n AI agent evaluations.

It depends on which item failed, which I didn't expect. Most people pair parser nodes with On Error: Continueso one bad item doesn't kill the batch. In that mode the failed items come out as {"error": "..."}, and the engine decides whether to retry by looking at one place:

// n8n-core 2.46.6, workflow-execute.js
const checkFailure = (data) =>
  !isEngineRequest(data) && isErrorValue(data.data?.[0]?.[0]?.json?.error);
//                                              ^ first output, first item only

To test it without depending on model luck, I pointed the Gemini credential's host at a local stub that returned valid JSON for chosen items and a plain sentence for the rest. Retry On Fail was on, 3 tries, 1 second apart:

• Item 0 bad, items 1 to 9 good: the node ran three times, all 10 items each time. 30 model calls, 27 of them for items that had already worked, and item 0 still failed.
• Item 0 good, items 1 to 9 bad: no retry at all. 10 calls, 9 errors passed straight through.
• All 10 truncated (real Gemini, 40 tokens):30 calls, 10 failures. A retry can't fix a deterministic cause.

The engine also caps it at 5 tries and 5 seconds between them, whatever you type in the fields. So Retry On Fail is the wrong tool for parser errors when On Error is set to continue. What works is routing them: set the chain to Continue (using error output) and send the failed items to a second chain with a bigger token budget, or to your error workflow if you want a human to see them. The control-flow patterns for agent failures post has the branch layout I use.

1. Open the model sub-node's output for a failed item and copy the raw text and finishReason. Diagnose from that, not from the parser message.
2. Truncated? Raise Maximum Number of Tokens. This was the only cause I could reproduce on demand with a real model.
3. Valid JSON without output?That's the "empty response" error. Use the AI Agent, which wraps it, or parse in a Code node.
4. Wrong type, null or missing field? Every field from a JSON example is required and typed by the example. Switch to a manual JSON Schema if a field is optional or can be null.
5. Odd fences or prose around bare JSON? Tell the model to return only a ```json block, or post-process the text yourself.
6. Leave Auto-Fix off for anything where the values matter, and route errors with the error output instead of counting on Retry On Fail.

The official Structured Output Parser docs cover the settings. They don't cover the item-0 retry rule or the misleading empty message, which is why I went to the source.

Everything ran on November 6, 2026 in throwaway n8nio/n8n:stable containers (2.46.6, which the Docker stable tag pointed to that day) on my Mac mini. Node versions: Structured Output Parser 1.3, Basic LLM Chain 1.9, AI Agent 3.1, Google Gemini Chat Model on gemini-3.1-flash-lite. The 17-case table comes from loading the image's own N8nStructuredOutputParser class in Node with a stub context. The workflows ran through n8n executewith per-item results read from the execution data: 220 real Gemini calls across 17 workflows, plus 60 calls to a local stub for the retry and wrapper tests. The leads were made-up businesses. The model results are one model on one day, so treat "130 of 130" as a sign to check other causes first, not as a promise. The retry rule, the wrapper behavior and the fix prompt come from the 2.46.6 source and were each confirmed by a run. If you're choosing between chains and agents for jobs like this, my agent tool vs sub-workflow post covers that.