n8n Expression Error Diagnosis

Diagnose and fix expression evaluation failures in n8n v1.x workflows. For error type details see references/methods.md. For before/after fixes see references/examples.md. For anti-patterns see references/anti-patterns.md.

Quick Diagnostic Table

Variable Availability Matrix

Use this matrix to determine which variables are available in each context.

Decision Tree: Expression Not Working

Expression returns unexpected result
|
+-- Is the variable available in this context?
|   +-- NO --> Check Variable Availability Matrix above
|   +-- YES --> Continue
|
+-- Does the field exist on the item?
|   +-- Check with: {{ Object.keys($json) }}
|   +-- Field missing --> Fix field name or check upstream node output
|   +-- Field exists --> Continue
|
+-- Is the value null/undefined/empty?
|   +-- YES --> Use $ifEmpty($json.field, fallback)
|   +-- NO --> Continue
|
+-- Is the type correct?
|   +-- String where number expected --> Number($json.field)
|   +-- Number where string expected --> String($json.field)
|   +-- String where date expected --> $json.field.toDateTime()
|   +-- Type is correct --> Continue
|
+-- Is item linking the problem?
|   +-- "Paired item not found" error --> See Paired Item Errors below
|   +-- Wrong item data --> Use explicit .first()/.all() instead of .item
|   +-- Correct linking --> Check expression syntax

Paired Item Error Resolution

When you see "Paired item not found" or get wrong data from $("<Node>").item:

1. Identify the break point — Item linking breaks when a node changes item count (e.g., aggregation, split, filter removes items).
2. Use explicit access instead:

• $("<Node>").first() — ALWAYS returns first item (safe fallback)
• $("<Node>").all()[index] — Access by position
• $("<Node>").itemMatching(currentIndex) — Trace back from current item (preferred in Code node)

1. In Code node — NEVER use $("<Node>").item. ALWAYS use $("<Node>").itemMatching(index).

JMESPath Parameter Order

n8n uses $jmespath(object, searchString) — this is the OPPOSITE of the JMESPath spec's search(searchString, object).

// CORRECT — object first, search string second
{{ $jmespath($json.data, "[*].name") }}

// WRONG — search string first (JMESPath spec order)
{{ $jmespath("[*].name", $json.data) }}

ALWAYS verify: first argument is the data object, second argument is the query string.

Static Data Pitfalls

$getWorkflowStaticData() has specific constraints:

• NOT available during manual test execution — returns empty object {}
• ONLY populated when workflow runs via trigger/webhook in production
• Data persists across executions but ONLY after successful completion
• NEVER store large data — keep static data small (IDs, timestamps, counters)
• May be unreliable during high-frequency parallel executions

Common Error Messages Reference

Code Node Specific Restrictions

ALWAYS remember these restrictions when writing Code node logic:

1. $itemIndex — NOT available. Use loop index or items.indexOf(item).
2. $secrets — NOT available. Use $env.SECRET_NAME instead.
3. $("<Node>").item — NOT recommended. Use $("<Node>").itemMatching(index).
4. No HTTP requests — use HTTP Request node before/after Code node.
5. No file system access — use Read/Write Files nodes.
6. Python: ALWAYS use bracket notation item["json"]["field"], NEVER dot notation.
7. Python on Cloud: NEVER import external libraries.

$response Context Restriction

$response is ONLY available in HTTP Request node parameter fields:

If you need HTTP response data in other nodes, the HTTP Request node automatically outputs the response as $json for downstream nodes.

Null/Undefined Handling Strategy

ALWAYS handle potentially missing data with one of these approaches:

1. `$ifEmpty(value, fallback)` — Best for simple fallback values
2. Optional chaining — $json.parent?.child?.value for nested access
3. Ternary — {{ $json.field ? $json.field : "default" }} for conditional logic
4. IIFE for complex logic:

   {{ (function() {
     const val = $json.field;
     if (val === null || val === undefined) return "N/A";
     return val.toString();
   })() }}

Type Conversion Quick Reference

Reference Files

• references/methods.md — Expression error types and variable availability details
• references/examples.md — Common expression errors with before/after fixes
• references/anti-patterns.md — Expression anti-patterns to avoid