n8n Error Handling & Execution Failures

Quick Reference

Error Handling Decision Tree

Workflow execution fails
├── Is the failure transient (API timeout, rate limit)?
│   ├── YES → Enable Retry on Fail on that node
│   │         Config: maxTries=3, waitBetweenTries=1000ms
│   │         └── Still fails after retries? → Falls to Error Workflow
│   └── NO → Continue below
├── Should the workflow continue despite this node failing?
│   ├── YES → Enable continueOnFail on that node
│   │         └── Check $json.error in next node for fallback logic
│   └── NO → Continue below
├── Is this a business logic validation failure?
│   ├── YES → Use Stop And Error node to fail explicitly
│   │         └── Error Workflow receives the custom error message
│   └── NO → Continue below
└── Unhandled failure
    └── ALWAYS configure an Error Workflow to catch it
        └── Error Trigger → Slack/Email/Database notification

The 4 Error Handling Patterns

Pattern 1: Error Workflow with Notifications

When: ALWAYS set up as a safety net for every production workflow.

Main Workflow → (fails) → Error Trigger → Slack/Email notification

Setup:

1. Create a new workflow with an Error Trigger node as the start
2. Add notification nodes (Slack, Email, HTTP Request to logging service)
3. In the main workflow, open Workflow Settings
4. Select the error workflow from the Error Workflow dropdown
5. One error workflow can serve multiple production workflows

Pattern 2: Graceful Degradation (continueOnFail)

When: The failing node is non-critical and a fallback value is acceptable.

HTTP Request (continueOnFail=true) → IF ($json.error) → Fallback path
                                                       → Success path

• Enable Continue On Fail in the node's Settings tab
• The next node receives error data in $json.error instead of normal output
• ALWAYS add an IF node after to branch on error vs success

Pattern 3: Retry with Fallback

When: The node calls an external API that may have transient failures.

API Call (retryOnFail=true, maxTries=3) → (still fails) → Error Workflow

• Enable Retry On Fail in the node's Settings tab
• Configure Max Tries (default: 3) and Wait Between Tries (default: 1000ms)
• If all retries fail, the error propagates to the Error Workflow

Pattern 4: Deliberate Failure (Stop And Error)

When: Custom validation detects invalid data that MUST stop execution.

IF (invalid data) → Stop And Error → triggers Error Workflow

• Add a Stop And Error node after your validation logic
• Set a descriptive error message explaining what failed
• The Error Workflow receives this message in the error data

Diagnostic Table: Symptom > Cause > Fix

Error Workflow Data Structure

The Error Trigger node receives this data when an error workflow fires:

{
  "execution": {
    "id": "231",
    "url": "https://n8n.example.com/execution/231",
    "retryOf": null,
    "error": {
      "message": "The error message",
      "stack": "Error stack trace..."
    },
    "lastNodeExecuted": "HTTP Request",
    "mode": "trigger"
  },
  "workflow": {
    "id": "1",
    "name": "My Workflow"
  }
}

Key fields:

• execution.error.message — The actual error description
• execution.lastNodeExecuted — Which node failed
• execution.id — Link back to the failed execution for inspection
• workflow.name — Which workflow triggered the error

Execution Timeout Configuration

ALWAYS set EXECUTIONS_TIMEOUT in production to prevent runaway executions.

Common Execution Errors

Authentication & Credentials

• "401 Unauthorized" — Credential expired or revoked. Re-authenticate in n8n.
• "403 Forbidden" — API key lacks required permissions. Check scopes.
• "ECONNREFUSED" — Target service is down or URL is wrong. Verify host/port.

Data & Processing

• "Cannot read property of undefined" — Expression references missing field. Use $json?.field optional chaining.
• "Too many items" — Node received more items than it can process. Add a Limit node upstream.
• "Payload too large" — Request exceeds N8N_PAYLOAD_SIZE_MAX (default 16MB). Reduce payload or increase limit.

Execution Environment

• "Execution was stopped because it reached the timeout" — Increase timeout or optimize workflow.
• "Worker timed out" — In queue mode, worker exceeded task runner timeout. Increase N8N_RUNNERS_TASK_TIMEOUT.
• "Out of memory" — Workflow processes too much data in memory. Use streaming or split into batches.

Rules

• ALWAYS configure an Error Workflow for every production workflow
• ALWAYS start error workflows with the Error Trigger node
• ALWAYS set EXECUTIONS_TIMEOUT in production environments
• ALWAYS add an IF node after a continueOnFail node to handle the error branch
• NEVER assume retries will solve non-transient errors (auth failures, schema mismatches)
• NEVER use continueOnFail on critical nodes where failure means data is invalid
• NEVER leave production workflows without error handling — silent failures cause data loss
• ALWAYS test error workflows by deliberately triggering them (use Stop And Error node)

Reference Files

• methods.md — Error handling nodes, continueOnFail API, retry configuration
• examples.md — Error workflow setup, continueOnFail patterns, retry patterns
• anti-patterns.md — Error handling mistakes to avoid