7 n8n Errors Every Beginner Hits (and How to Fix Them)

Osama Mohamed — Sat, 14 Nov 2026 20:50:37 +0000

If you've built more than a couple of n8n workflows, you've stared at a red error box that made no sense. The good news: almost every beginner error comes from one of two things. Either the data isn't shaped the way you think, or the node you're referencing didn't run.

Here are the seven errors I see most often, what each one actually means, and the fix that works.

1. Cannot read properties of undefined (reading '...')

What it means: you asked for a field inside something that doesn't exist for this item. For example $json.order.shipping.country when one order has no shipping block.

How to tell which case you're in: if every item fails, you probably have a typo in a parent field name. If only some items fail, the data is genuinely missing for those items.

Fix: use optional chaining plus a default value:

{{ $json.order?.shipping?.country ?? 'Unknown' }}

?. stops at the first missing level instead of crashing, and ?? gives a fallback.
Full walkthrough: Cannot read properties of undefined in n8n

2. .map is not a function

What it means: you called .map() on something that isn't an array. Two usual suspects:

The array arrived as a JSON string ("[\"a\",\"b\"]"). Forms, Google Sheets cells and some APIs do this.
An API returns a single object when there's one result and an array only when there are several.

Fix for the string case:

{{ JSON.parse($json.tags).map(t => t.toUpperCase()) }}

For the "sometimes object, sometimes array" case, [].concat($json.tags) always gives you an array.
More causes and fixes: .map is not a function in n8n

3. Unexpected token o in JSON at position 1

This one looks cryptic, but it has a funny explanation. When you JSON.parse() something that is already an object, JavaScript first turns it into the text "[object Object]". The character at position 1 is o, so the parse fails.

n8n's Webhook and HTTP Request nodes usually parse JSON for you, so the extra JSON.parse() is the bug. (If you see Unexpected token <, the API returned an HTML error page instead of JSON.)

Fix: only parse when the value is actually a string:

{{ (typeof $json.data === 'string' ? JSON.parse($json.data) : $json.data).plan }}

Details: Unexpected token in JSON in n8n

4. JSON parameter needs to be valid JSON

You'll hit this in the HTTP Request node when you build a JSON body by hand and drop expressions into it. It breaks as soon as a value contains a double quote or a line break (customer messages and AI output are the usual culprits), or when you forget the quotes around a text expression.

Fix: stop hand-writing the JSON. Build the whole body as an object and let JSON.stringify() handle the escaping:

{{ JSON.stringify({ name: $json.name, note: $json.note }) }}

Step by step: JSON parameter needs to be valid JSON

5. Referenced node is unexecuted

$('Some Node') only works if that node actually ran in this execution. It fails when:

the node sits on the other branch of an IF or Switch that wasn't taken, or
the node is connected after the current one, not before it, or
you're testing a single node and the earlier nodes haven't been executed yet.

Fix: reference a node that runs on every path (for example the trigger or a lookup before the IF). If you need data from both branches, bring them back together with a Merge node first.

More: Referenced node is unexecuted

6. Paired item data for item from node is unavailable

n8n quietly tracks which input item produced each output item. That's what makes $('Node').item work. The link breaks when a Code node builds brand-new items or when Aggregate, Summarize or Merge combine several items into one.

Fix: when the earlier node had a single item, read it directly:

{{ $('Webhook').first().json.body.email }}

If you write the Code node yourself, you can keep the link by returning pairedItem with each new item.
Explained with examples: Paired item data is unavailable

7. The requested webhook is not registered

Every Webhook node has two URLs, and this error almost always means you're using the wrong one:

Test URL (/webhook-test/...) only listens while you're in the editor waiting for a test event.
Production URL (/webhook/...) only works when the workflow is active.

Fix: point your form or app at the production URL and activate the workflow. Use the test URL only while you're building.

Checklist: The requested webhook is not registered

The 3-step habit that prevents most of these

Look at the real input in the node's input panel before writing an expression. Don't assume the shape.
Expect missing and inconsistent data. Use ?., ?? and type checks.
Make sure the node you reference ran for this item.

Want to practice instead of just reading?

I put together free, interactive n8n and Make.com labs at WorkflowExercise. You get a real JSON payload and a broken or missing expression, and your answer is executed against test data, so you know if it actually works. The full list of error fixes is here: n8n & Make error fixes.

Which n8n error cost you the most time? Drop it in the comments and I'll add a fix for it.

Disclosure: I built WorkflowExercise. It's an independent project, not affiliated with n8n.

DEV Community: Osama Mohamed