node cookbook
N8N Code Node Cookbook
Use the Code node when built-in nodes cannot express the required transformation, branching, formatting, or lightweight custom logic.
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, JavaScript, Python
- 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
Use the Code node when built-in nodes cannot express the required transformation, branching, formatting, or lightweight custom logic.
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.
Version awareness
Last reviewed 2026-05-21
Key Facts
- Node role
- Run custom code inside a workflow.
- Best fit
- Data transformation, cleanup, custom mapping, and small pieces of logic.
- Risk
- Large or inefficient code can contribute to memory and execution issues.
- Common companion nodes
- Set, IF, HTTP Request, Webhook, and database nodes.
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
- Use built-in nodes first when they cover the transformation.
- Keep Code node logic small and focused.
- Validate item shapes before accessing nested fields.
- Test with representative input data.
- Move very heavy processing outside n8n if it becomes resource-intensive.
Verification
- The output item shape matches downstream node expectations.
- Empty and malformed inputs are handled.
- Execution time and memory stay acceptable with real data.
Warnings
- Complex Code nodes are harder for non-developers to maintain.
- Large data transformations can increase memory pressure.
Production Cookbook
Common production use cases
- Normalize irregular payloads.
- Build deterministic dedupe keys.
- Transform arrays before writing to another system.
Required credentials/scopes
- No credential required by the node itself; upstream/downstream nodes still need least-privilege credentials.
Input fields that usually break
- Returning raw objects instead of items.
- Mutating item shape unexpectedly.
- Assuming every item has the same nested field.
Common errors
- Cannot read properties of undefined.
- Code returns non-array item format.
- Manual test uses pinned data that production never receives.
[
{
"json": {
"eventId": "evt_123",
"normalized": true
}
}
]Small working pattern
Map each input item to a new `{ json: ... }` object and include defaults for optional fields.
Related recipes using this node
When to use HTTP Request or Code instead: Use Set or IF for simple mapping/branching; reserve Code for transformations that cannot be expressed clearly with built-in nodes.