Error Handling

n8n provides comprehensive error handling mechanisms at multiple levels: node-level, workflow-level, and system-level. Understanding these mechanisms helps you build resilient workflows that gracefully handle failures.

Error Types

n8n uses a hierarchical error system with specific error classes:

Node Errors

NodeOperationError
NodeApiError
ExpressionError
WorkflowError

Errors that occur during node execution:

// From errors/node-operation.error.ts
export class NodeOperationError extends NodeError {
  constructor(
    node: INode,
    error: Error | string | JsonObject,
    options: NodeOperationErrorOptions = {}
  ) {
    // Error context
    this.context.runIndex = options.runIndex;
    this.context.itemIndex = options.itemIndex;
    this.context.metadata = options.metadata;
    
    // Severity level
    this.level = options.level ?? 'warning';
  }
}

When to use:

Invalid credentials
API rate limiting
Invalid parameters
Business logic errors

Example:

throw new NodeOperationError(
  this.getNode(),
  'Invalid API key provided',
  {
    itemIndex: i,
    description: 'Check your API credentials in node settings'
  }
);

Errors from external API calls:

export class NodeApiError extends NodeError {
  httpCode?: string;
  
  constructor(
    node: INode,
    error: JsonObject,
    options: NodeApiErrorOptions = {}
  ) {
    this.httpCode = error.statusCode?.toString();
    this.context.request = options.request;
  }
}

When to use:

HTTP request failures
API errors with status codes
External service unavailability

Example:

throw new NodeApiError(
  this.getNode(),
  {
    statusCode: 429,
    message: 'Rate limit exceeded'
  },
  {
    request: requestOptions
  }
);

Errors in expression evaluation:

export class ExpressionError extends Error {
  context: {
    expression: string;
    parameter: string;
    node: string;
  };
}

When thrown:

Syntax errors in expressions
Type errors in expression evaluation
Undefined variable access

Example:

// Expression: {{$json.user.email}}
// When $json.user is undefined
throw new ExpressionError(
  "Cannot read property 'email' of undefined",
  { expression, parameter: 'email', node: 'HTTP Request' }
);

Workflow-level errors:

export class WorkflowOperationError extends Error {}
export class WorkflowActivationError extends Error {}

Examples:

Workflow cannot be activated
Missing required nodes
Invalid workflow structure
Circular dependencies

Node-Level Error Handling

Retry Configuration

Nodes can automatically retry on failure:

const node: INode = {
  name: 'HTTP Request',
  type: 'n8n-nodes-base.httpRequest',
  typeVersion: 1,
  position: [450, 300],
  parameters: {
    url: 'https://api.example.com/data'
  },
  // Retry configuration
  retryOnFail: true,
  maxTries: 3,
  waitBetweenTries: 1000  // milliseconds
};

First Attempt

Node executes normally. If it succeeds, execution continues.

Failure Detected

If the node throws an error and retryOnFail is true, the retry mechanism activates.

Wait Period

System waits for waitBetweenTries milliseconds before retrying.

Retry Attempts

Node executes again. This continues up to maxTries times.

Final Result

If any attempt succeeds, execution continues
If all attempts fail, error handling logic applies

Continue on Fail

Control whether workflow execution stops on node failure:

const node: INode = {
  name: 'Optional API Call',
  type: 'n8n-nodes-base.httpRequest',
  typeVersion: 1,
  position: [450, 300],
  parameters: {},
  continueOnFail: true,      // Don't stop workflow
  alwaysOutputData: true     // Output data even on error
};

const node = {
  continueOnFail: false,
  alwaysOutputData: false
};
// Behavior:
// - Error thrown
// - Workflow execution stops
// - Error workflow triggered (if configured)
// - No data passed to next nodes

Error Data Structure

When alwaysOutputData is true, failed items include error information:

interface INodeExecutionData {
  json: IDataObject;
  error?: {
    message: string;
    stack?: string;
    context?: {
      itemIndex?: number;
      runIndex?: number;
      parameter?: string;
    };
  };
}

// Example error data
const errorOutput: INodeExecutionData = {
  json: {
    // Original input data
    id: 123,
    url: 'https://api.example.com/user/123'
  },
  error: {
    message: 'Request failed with status code 404',
    context: {
      itemIndex: 2,
      runIndex: 0
    }
  }
};

Workflow-Level Error Handling

Error Workflow

Configure a dedicated error workflow to handle failures:

const workflowSettings: IWorkflowSettings = {
  errorWorkflow: 'error-handler-workflow-id'
};

The error workflow receives:

interface IExecutionError {
  execution: {
    id: string;
    mode: WorkflowExecuteMode;
    startedAt: Date;
    workflowId: string;
    workflowName: string;
  };
  workflow: {
    id: string;
    name: string;
  };
  node: {
    name: string;
    type: string;
    parameters: INodeParameters;
  };
  error: {
    message: string;
    stack?: string;
    context?: IDataObject;
  };
}

Error workflows run in error mode and receive the complete error context, allowing you to:

Send error notifications (email, Slack, etc.)
Log errors to external services
Trigger recovery workflows
Store error details for analysis

Error Trigger Node

The Error Trigger node starts workflows when errors occur:

// Error Trigger configuration
const errorTrigger: INode = {
  name: 'Error Trigger',
  type: 'n8n-nodes-base.errorTrigger',
  typeVersion: 1,
  position: [250, 300],
  parameters: {}
};

// Next node can access error data
const emailNode: INode = {
  name: 'Send Email',
  type: 'n8n-nodes-base.emailSend',
  typeVersion: 1,
  position: [450, 300],
  parameters: {
    subject: '={{"Workflow Error: " + $json.workflow.name}}',
    text: '={{$json.error.message}}',
    html: `={
      Workflow: {{$json.workflow.name}}<br>
      Node: {{$json.node.name}}<br>
      Error: {{$json.error.message}}<br>
      Time: {{$json.execution.startedAt}}
    }`
  }
};

Execution-Level Error Handling

Execution Errors

The execution engine tracks errors throughout workflow execution:

// From workflow-execute.ts
interface IRun {
  data: IRunData;
  mode: WorkflowExecuteMode;
  startedAt: Date;
  stoppedAt?: Date;
  status: ExecutionStatus;  // 'new', 'running', 'success', 'error', 'canceled'
  error?: ExecutionError;
}

// Execution status values
type ExecutionStatus = 
  | 'new'       // Just created
  | 'running'   // Currently executing
  | 'success'   // Completed successfully
  | 'error'     // Failed with error
  | 'waiting'   // Waiting for external event
  | 'canceled'; // Manually canceled

Timeout Handling

const workflowSettings: IWorkflowSettings = {
  executionTimeout: 3600  // seconds
};

// From workflow-execute.ts
class WorkflowExecute {
  timedOut: boolean = false;
  
  // Timeout causes execution to cancel
  // Throws: TimeoutExecutionCancelledError
}

Manual Cancellation

// Cancel an active execution
workflowExecute.abortController.abort();

// Throws: ManualExecutionCancelledError

Error Recovery Patterns

Pattern 1: Graceful Degradation

Continue with default values when optional operations fail:

// In IF node or expression
{{
  $node["Optional API"].json !== undefined
    ? $node["Optional API"].json.data
    : { defaultValue: true }
}}

Pattern 2: Error Notification

Notify team when critical operations fail:

Configure Error Workflow

Set error workflow in workflow settings

Add Error Trigger

Start error workflow with Error Trigger node

Send Notification

Use Slack, Email, or webhook to alert team

Pattern 3: Fallback Service

Try alternate services if primary fails:

// Primary service node
const primaryNode: INode = {
  name: 'Primary API',
  continueOnFail: true,
  alwaysOutputData: true
};

// IF node checks for error
const ifNode: INode = {
  name: 'Check Error',
  parameters: {
    conditions: {
      boolean: [
        {
          value1: '={{$json.error !== undefined}}',
          operation: 'equal',
          value2: true
        }
      ]
    }
  }
};

// Fallback service on true branch
const fallbackNode: INode = {
  name: 'Fallback API'
};

Pattern 4: Exponential Backoff

Implement custom retry with increasing delays:

// In Code node
const maxRetries = 5;
let attempt = 0;
let success = false;
let data = null;

while (attempt < maxRetries && !success) {
  try {
    data = await makeRequest();
    success = true;
  } catch (error) {
    attempt++;
    if (attempt < maxRetries) {
      const delay = Math.pow(2, attempt) * 1000;  // 2s, 4s, 8s, 16s, 32s
      await new Promise(resolve => setTimeout(resolve, delay));
    } else {
      throw error;
    }
  }
}

return { json: data };

Error Context and Debugging

Error Context Information

Errors include detailed context for debugging:

class NodeError extends Error {
  node: INode;
  context: {
    itemIndex?: number;      // Which item failed
    runIndex?: number;        // Which execution run
    parameter?: string;       // Which parameter caused error
    data?: IDataObject;      // Additional context
  };
  description?: string;       // User-friendly description
  httpCode?: string;         // HTTP status code
  cause?: Error;             // Original error
}

Accessing Error Details

In error workflows or subsequent nodes:

// Error message
{{$json.error.message}}

// Stack trace
{{$json.error.stack}}

// Failed node information
{{$json.node.name}}
{{$json.node.type}}

// Execution context
{{$json.execution.mode}}
{{$json.execution.startedAt}}

// Item that caused error
{{$json.error.context.itemIndex}}

Best Practices

Set appropriate retry counts: Too many retries can delay error detection
Use meaningful error messages: Include context for debugging
Configure error workflows: Set up centralized error handling
Handle errors close to source: Use continueOnFail judiciously
Log errors appropriately: Balance detail with noise
Test error scenarios: Deliberately trigger errors to test handling
Document error handling: Explain expected failures in workflow notes
Monitor error rates: Track and alert on unusual error patterns

Testing Error Handling:

Use the “Test workflow” button with invalid data
Temporarily set incorrect credentials to test auth errors
Use the IF node to simulate random failures
Test timeout behavior with long-running operations
Verify error workflows receive correct data

Common Error Scenarios

API Rate Limiting

const node: INode = {
  retryOnFail: true,
  maxTries: 5,
  waitBetweenTries: 60000  // Wait 1 minute between retries
};

Transient Network Errors

const node: INode = {
  retryOnFail: true,
  maxTries: 3,
  waitBetweenTries: 5000  // Wait 5 seconds
};

Optional Operations

const node: INode = {
  continueOnFail: true,
  alwaysOutputData: false  // Don't pass error data forward
};

Critical Operations

const node: INode = {
  retryOnFail: true,
  maxTries: 3,
  continueOnFail: false  // Stop on failure
};

const workflowSettings: IWorkflowSettings = {
  errorWorkflow: 'critical-error-handler'  // Alert team immediately
};

Getting Started

Self-Hosting

Building Workflows

AI Workflows

Node Development

CLI Reference

Error Handling

Error Handling

Error Types

Node Errors

Node-Level Error Handling

Retry Configuration

Continue on Fail

Error Data Structure

Workflow-Level Error Handling

Error Workflow

Error Trigger Node

Execution-Level Error Handling

Execution Errors

Timeout Handling

Manual Cancellation

Error Recovery Patterns

Pattern 1: Graceful Degradation

Pattern 2: Error Notification

Pattern 3: Fallback Service

Pattern 4: Exponential Backoff

Error Context and Debugging

Error Context Information

Accessing Error Details

Best Practices

Common Error Scenarios

API Rate Limiting

Transient Network Errors

Optional Operations

Critical Operations

Next Steps

Execution Modes

Creating Workflows

Build docs developers (and LLMs) love

Getting Started

Self-Hosting

Building Workflows

AI Workflows

Node Development

CLI Reference

Documentation Index

​Error Handling

​Error Types

​Node Errors

​Node-Level Error Handling

​Retry Configuration

​Continue on Fail

​Error Data Structure

​Workflow-Level Error Handling

​Error Workflow

​Error Trigger Node

​Execution-Level Error Handling

​Execution Errors

​Timeout Handling

​Manual Cancellation

​Error Recovery Patterns

​Pattern 1: Graceful Degradation

​Pattern 2: Error Notification

​Pattern 3: Fallback Service

​Pattern 4: Exponential Backoff

​Error Context and Debugging

​Error Context Information

​Accessing Error Details

​Best Practices

​Common Error Scenarios

​API Rate Limiting

​Transient Network Errors

​Optional Operations

​Critical Operations

​Next Steps

Execution Modes

Creating Workflows

Build docs developers (and LLMs) love

Error Handling

Error Types

Node Errors

Node-Level Error Handling

Retry Configuration

Continue on Fail

Error Data Structure

Workflow-Level Error Handling

Error Workflow

Error Trigger Node

Execution-Level Error Handling

Execution Errors

Timeout Handling

Manual Cancellation

Error Recovery Patterns

Pattern 1: Graceful Degradation

Pattern 2: Error Notification

Pattern 3: Fallback Service

Pattern 4: Exponential Backoff

Error Context and Debugging

Error Context Information

Accessing Error Details

Best Practices

Common Error Scenarios

API Rate Limiting

Transient Network Errors

Optional Operations

Critical Operations

Next Steps