debug-workflow

n8n Workflow Debugging

Fix n8n workflows the way a senior engineer does — systematically, not by guessing.

Triage: identify the failure class first

Ask the user (or infer from error text) which class:

Class	Symptom	Common root causes
Expression error	Cannot read property X of undefined, red node badge	Wrong expression syntax, missing = prefix, accessing undefined fields
Type mismatch	Expected string, got array, downstream weirdness	Item Lists vs single item confusion, Split In Batches output shape
Silent empty	Workflow runs green but no output/side effect	Filter condition wrong, pinned stale data, credential scope
Auth failure	401, 403, Invalid API key	Wrong credential selected, expired token, OAuth refresh not configured
Rate limit	Intermittent 429, works manually, fails in batch	No backoff, batch too large, shared credential across workflows
Sub-workflow	Execute Workflow returns nothing or errors	Parameters not passed, return value not set, wrong workflow ID

Expression errors

The single biggest footgun: ={{ $json.field }} vs {{ $json.field }}. The leading = makes the field an expression. Without it, the literal string {{ $json.field }} is sent.

Check:

1. Click the field — does it show the "expression" toggle (fx icon) highlighted? If not, it's literal mode.
2. In code-view JSON, the value should start with =: "value": "={{ $json.id }}"

Accessing undefined paths: $json.customer.email throws if customer is null. Use optional chaining: $json.customer?.email ?? 'unknown'.

Referencing earlier nodes: Use $('Node Name').item.json.field, NOT $node['Node Name'].json.field (deprecated). Quote exact node name including spaces.

Common expression patterns:

// Array access
{{ $json.items[0].name }}
{{ $json.items?.[0]?.name ?? 'empty' }}

// Previous node output
{{ $('Webhook').item.json.body.email }}

// All items from previous node (for loops)
{{ $('Split In Batches').all().map(i => i.json.id) }}

// Conditional
{{ $json.amount > 100 ? 'high' : 'low' }}

// Date formatting (n8n uses Luxon)
{{ $now.toISO() }}
{{ $now.minus({ days: 7 }).toFormat('yyyy-MM-dd') }}

// Environment vars (self-hosted)
{{ $env.MY_SECRET }}