error fix
n8n Expression Error: Fix Item Shape, Missing Fields, and Branch Problems
An n8n expression error usually means the expression is reading the wrong runtime item shape: a missing field, an unexecuted branch, invalid JSON, or syntax that does not fit n8n's expression format.
Match your incident first
Start with the symptom you can prove
Referenced node did not execute
First check: Open the failed execution and inspect which branch produced the current item.
Wrong fix to avoid: Do not add dummy Set nodes just to silence the error without fixing data flow.
Verify: The expression handles both branch outcomes or references only nodes guaranteed to run.
Field is missing on some items
First check: Pin or inspect multiple real items, not only the first successful item.
Wrong fix to avoid: Do not hardcode array indexes before checking all item shapes.
Verify: The expression uses safe access/defaults and succeeds for empty, partial, and normal items.
Expression works in manual test but fails in production
First check: Compare pinned test data with a recent production execution payload.
Wrong fix to avoid: Do not rely on pinned data as proof of production behavior.
Verify: A fresh production execution with live data passes the same expression.
- Use when
- n8n workflows, expressions
- First check
- Inspect the runtime item shape from the previous node, not just the expression template.
- Time to check
- 5-10 minutes
- Next step
- Match the symptom, then run the verification checks.
Independent third-party notes. n8n is a trademark of its owner and is referenced only for compatibility and troubleshooting context.
Quick Answer
An n8n expression error usually means the expression is reading the wrong runtime item shape: a missing field, an unexecuted branch, invalid JSON, or syntax that does not fit n8n's expression format.
Does this match your symptom?
Expression or payload shape is failing
A node receives unexpected data, invalid JSON, missing fields, or an expression works only on one branch.
First check: Inspect the runtime item shape from the previous node, not just the expression template.
Problem Pattern
The expression worked for one item or branch but fails when data shape changes or a referenced node did not execute.
Version awareness
Last reviewed 2026-05-28
Key Facts
- Expression role
- Expressions are JavaScript-like snippets inside node parameters.
- Missing data
- n8n documents errors when an expression cannot retrieve referenced data.
- Unexecuted node
- A referenced node may not have run on the current path.
- Syntax issue
- Invalid expression syntax can fail before workflow logic runs.
Production Diagnostic Matrix
Turn checks into a brief| Exact symptom or log | Likely cause | First check | Wrong fix to avoid | Verification |
|---|---|---|---|---|
| Referenced node did not execute | Expression reads from a node on a branch that did not run for this item. | Open the failed execution and inspect which branch produced the current item. | Do not add dummy Set nodes just to silence the error without fixing data flow. | The expression handles both branch outcomes or references only nodes guaranteed to run. |
| Field is missing on some items | Input items have inconsistent shape, optional provider fields, or previous node output changed. | Pin or inspect multiple real items, not only the first successful item. | Do not hardcode array indexes before checking all item shapes. | The expression uses safe access/defaults and succeeds for empty, partial, and normal items. |
| Expression works in manual test but fails in production | Manual pinned data differs from live payload, timezone, credentials, or branch timing. | Compare pinned test data with a recent production execution payload. | Do not rely on pinned data as proof of production behavior. | A fresh production execution with live data passes the same expression. |
| Invalid JSON from HTTP Request or Set node | String interpolation produced invalid quoting, trailing commas, or unescaped newlines. | Validate the exact body sent by the node, not the visual expression preview only. | Do not wrap an already-object value in extra quotes. | The downstream node receives valid JSON and the response status is expected. |
| IF branch changes data shape | True and false outputs carry different fields, item counts, or nested paths. | Inspect both IF outputs and define a shared normalized shape before merge/response. | Do not assume the true branch schema exists on false branch items. | Both branches feed the next node with the same required fields. |
| Code node returns wrong item format | Code returns a raw object/array instead of an array of items with json fields. | Check the Code node return value against the required item format. | Do not return secrets or full credentials for debugging. | The next node receives items shaped like [{ json: {...} }]. |
Recommended Steps
- Read the exact expression error and identify the referenced node, field, and item index.
- Open the failed execution and inspect the input JSON at the node where the expression runs.
- Confirm the referenced node executed on the current branch for that item.
- Replace fragile paths with safe access, defaults, or a normalized Set/Edit Fields step where needed.
- Use a Code node for transformations that need loops, item reshaping, or defensive validation.
Verification
- The expression previews the expected value for the failing item, not only the first item.
- The workflow works on expected, empty, missing-field, and alternate-branch input cases.
- No referenced node is unexecuted on the tested branch.
- If a Code node is used, the next node receives items with a json object.
First Commands / Checks
Failed node: <node name>
Item index: <number>
Input JSON keys: id, customer, amount, status
Referenced expression: {{$json.customer?.email}}
Observed value: <missing | value | wrong type>True branch required keys: customerEmail, orderId, source
False branch required keys: customerEmail, orderId, source
Next node reads only these normalized keys: yesreturn items.map(item => ({
json: {
customerEmail: item.json.customer?.email ?? null,
needsReview: !item.json.customer?.email
}
}));Warnings
- Expressions can behave differently across branches if some nodes do not execute.
- Copying expressions between workflows without matching node names and data shapes often breaks.
Common Mistakes
- Referencing a node that did not run because an IF branch went the other way.
- Assuming every item has the same nested JSON shape.
- Leaving a trailing dot or malformed expression syntax.
- Using an expression for complex transformation better handled by Code.
Examples
Referenced node name correct: yes
Referenced node executed on this branch: yes
Input item has expected field: yes
Expression preview works: yes
Empty value case handled: yesRisky: {{$json.customer.email}}
Safer: {{$json.customer?.email || 'missing-email'}}
Then route missing-email through an IF node instead of letting a later API call fail silently.IF true branch uses data from Node A
IF false branch skips Node A
Later node references {{$node['Node A'].json.id}}
Result: expression fails on the false branch
Fix: merge/normalize data before the branch or handle each branch separatelyExpected shape before downstream nodes:
{
"customerEmail": "[email protected]",
"source": "stripe",
"needsReview": false
}
If customer.email is missing, set needsReview=true and route it explicitly.FAQ
Why does an expression fail only on one branch?
The referenced node may not execute on that branch, or the item data shape may differ after branching.
When should I use a Code node instead?
Use Code when the transformation needs loops, complex conditionals, reshaping arrays, or defensive checks that are hard to read inline.