# How to Troubleshoot n8n Errors

- Tool: n8n
- Difficulty: Beginner
- Time required: 15 minutes
- Compatibility: n8n 1.0+ (self-hosted, Docker, and n8n Cloud)
- Last updated: March 2026

## TL;DR

Troubleshoot n8n errors by checking the execution history for failed runs, inspecting node input/output data, enabling debug logging with N8N_LOG_LEVEL=debug, and using the built-in error workflow feature. Most errors fall into credential issues, data format mismatches, API rate limits, or timeout failures, each with a specific diagnostic path.

## Why Learn to Troubleshoot n8n Errors Systematically

When an n8n workflow fails, the error message alone rarely tells the full story. A systematic troubleshooting approach helps you find the root cause faster, whether it is a misconfigured credential, unexpected data format, API rate limit, or timeout. n8n provides several built-in tools for diagnosing issues: execution history with full data snapshots, per-node input/output inspection, configurable logging levels, and error trigger workflows. Learning to use these tools effectively saves hours of debugging and prevents recurring failures.

## Before you start

- A running n8n instance (self-hosted or n8n Cloud)
- At least one workflow that has failed or is producing unexpected results
- For server-side logging: access to the terminal or Docker logs
- Basic understanding of n8n node types and data flow

## Step-by-step guide

### 1. Check the execution history for failed runs

The execution history is your first stop for troubleshooting. Navigate to the Executions tab in the n8n editor (left sidebar). Filter by status to show only failed executions. Click on a failed execution to see the full workflow state at the time of failure. Each node shows whether it succeeded or failed, and you can click any node to see its input and output data. The execution that triggered the error is highlighted in red with the error message displayed directly on the node.

```
// Execution history shows:
// - Timestamp of the execution
// - Status: Success, Error, or Running
// - Workflow name
// - Execution duration
// - Mode: Manual, Trigger, Webhook, or Retry
//
// Click a failed execution to see:
// - Which node failed (highlighted in red)
// - The exact error message
// - Input data that caused the failure
// - Output data from preceding nodes
```

**Expected result:** You can see all failed executions with timestamps. Clicking one opens the workflow state showing exactly which node failed and why.

### 2. Inspect node input and output data

Most n8n errors are caused by unexpected data reaching a node. Click on the failed node, then examine the Input tab to see what data it received. Compare this to what the node expects. Common data issues include: missing fields the node requires, wrong data types (string instead of number), empty arrays when the node expects at least one item, and nested JSON structures that need flattening. Also check the previous node's Output to verify it is producing the expected data shape.

```
// Common data issues to check:
//
// 1. Missing field:
//    Expected: {{ $json.email }}
//    Actual input: { "name": "John" }  ← no email field
//
// 2. Wrong data type:
//    Expected: number for price calculation
//    Actual input: { "price": "29.99" }  ← string, not number
//
// 3. Empty input:
//    Expected: at least one item
//    Actual input: []  ← no items, node has nothing to process
//
// 4. Nested data:
//    Expected: {{ $json.name }}
//    Actual input: { "data": { "user": { "name": "John" } } }
//    Fix: {{ $json.data.user.name }}
```

**Expected result:** You can see the exact data that reached the failed node and identify mismatches between expected and actual input.

### 3. Enable debug logging for server-side diagnostics

When the execution history does not provide enough detail, enable debug logging on the server. Set N8N_LOG_LEVEL=debug to see HTTP requests, credential lookups, expression evaluations, and internal operations. This is especially useful for diagnosing authentication failures, network connectivity issues, and expression evaluation errors. Remember to switch back to info or warn after debugging to avoid log noise and potential security exposure.

```
# Enable debug logging
export N8N_LOG_LEVEL=debug
export N8N_LOG_OUTPUT=console

# Restart n8n to apply
n8n start

# In Docker:
docker stop n8n
docker run -d --name n8n \
  -e N8N_LOG_LEVEL=debug \
  -p 5678:5678 \
  -v n8n_data:/home/node/.n8n \
  docker.n8n.io/n8nio/n8n

# View logs in Docker:
docker logs n8n --tail 100 -f

# After debugging, switch back:
export N8N_LOG_LEVEL=info
```

**Expected result:** n8n outputs detailed logs including HTTP request/response bodies, credential resolution, and expression evaluation details.

### 4. Diagnose common error categories

Most n8n errors fall into five categories, each with a specific diagnostic path. Identifying the category first saves time by focusing your investigation. Check the error message text and the node type to determine which category applies, then follow the corresponding troubleshooting steps.

```
// Category 1: Credential errors
// Messages: "401 Unauthorized", "Invalid API key", "Authentication failed"
// Fix: Verify credentials in Settings → Credentials. Test by creating a new credential.

// Category 2: Data format errors
// Messages: "Cannot read property X of undefined", "Expected string, got object"
// Fix: Inspect the input data on the failing node. Add a Set or Code node to transform data.

// Category 3: Rate limit errors
// Messages: "429 Too Many Requests", "Rate limit exceeded"
// Fix: Add a Wait node between API calls, use SplitInBatches, or reduce trigger frequency.

// Category 4: Timeout errors
// Messages: "ETIMEDOUT", "Timeout exceeded", "socket hang up"
// Fix: Increase node timeout in Settings, check API server status, reduce request payload.

// Category 5: Expression errors
// Messages: "Expression evaluation error", "Cannot read property of null"
// Fix: Check expression syntax. Use optional chaining: {{ $json.field?.subfield }}.
```

**Expected result:** You can categorize any n8n error into one of five types and follow the specific diagnostic steps for that category.

### 5. Set up an error trigger workflow for automated monitoring

Instead of manually checking for failures, create a dedicated error monitoring workflow. Add an Error Trigger node as the start of a new workflow. It fires whenever any workflow in your n8n instance fails. Connect it to notification nodes (Slack, email, or database) to log error details automatically. This gives you proactive monitoring so you discover failures immediately instead of hours or days later.

```
// Error monitoring workflow
// Node 1: Error Trigger
// Node 2: Code node to format the error
const execution = $json.execution;
const workflow = $json.workflow;

return [{
  json: {
    alert: `Workflow "${workflow.name}" failed`,
    error: execution.error?.message || 'Unknown error',
    executionId: execution.id,
    timestamp: new Date().toISOString(),
    mode: execution.mode,
    url: `https://n8n.example.com/execution/${execution.id}`
  }
}];

// Node 3: Send to Slack, Email, or save to database
```

**Expected result:** Every workflow failure triggers an automatic notification with the workflow name, error message, and a link to the failed execution.

## Complete code example

File: `troubleshooting-checklist.js`

```javascript
// Code node: Automated troubleshooting data collector
// Add this to any workflow for debugging — it captures the full context

const items = $input.all();

// Collect environment info
const debugInfo = {
  // Workflow context
  workflowName: $workflow.name,
  workflowId: $workflow.id,
  executionId: $execution.id,
  executionMode: $execution.mode,
  timestamp: new Date().toISOString(),

  // Input data summary
  inputItemCount: items.length,
  inputFields: items.length > 0 ? Object.keys(items[0].json) : [],
  firstItem: items.length > 0 ? items[0].json : null,

  // Data validation checks
  checks: {
    hasItems: items.length > 0,
    firstItemHasData: items.length > 0 && Object.keys(items[0].json).length > 0,
    noErrorField: items.length > 0 && !items[0].json.error,
    allFieldsPresent: items.length > 0 && !Object.values(items[0].json).includes(undefined)
  }
};

// Flag any issues
const issues = [];
if (!debugInfo.checks.hasItems) issues.push('No input items received');
if (!debugInfo.checks.firstItemHasData) issues.push('First item is empty');
if (!debugInfo.checks.noErrorField) issues.push('Error field detected in input');
if (!debugInfo.checks.allFieldsPresent) issues.push('Some fields are undefined');

debugInfo.issues = issues;
debugInfo.status = issues.length === 0 ? 'OK' : 'ISSUES_FOUND';

// Pass through original items plus debug info
return [
  {
    json: {
      _debug: debugInfo,
      ...items[0]?.json
    }
  },
  ...items.slice(1)
];
```

## Common mistakes

- **Looking only at the error message without checking the input data** — undefined Fix: Most errors are caused by unexpected input data. Always inspect the Input tab on the failing node to see what data it received.
- **Leaving N8N_LOG_LEVEL=debug in production permanently** — undefined Fix: Debug logs can expose sensitive data and consume disk space. Set it to debug only for active troubleshooting, then revert to info or warn.
- **Not saving execution data for failed runs** — undefined Fix: Set EXECUTIONS_DATA_SAVE_ON_ERROR=all in your environment variables so failed executions are always saved for later inspection.
- **Ignoring intermittent errors because they resolve themselves** — undefined Fix: Intermittent errors often indicate rate limits, timeouts, or resource constraints that worsen over time. Investigate and add error handling.

## Best practices

- Always check the execution history first — it shows exactly which node failed and what data it received
- Inspect both input and output on the failing node to understand the data flow
- Enable debug logging temporarily for hard-to-diagnose issues, then switch back to info level
- Set up an error trigger workflow to receive immediate notifications about failures
- Save execution data for both successful and failed runs to compare behavior
- Use data pinning to reproduce errors with the exact same input data
- Document common errors and their solutions in your team's knowledge base
- Test each node individually using the Execute Node button before running the full workflow

## Frequently asked questions

### Where do I find the error message for a failed workflow?

Go to the Executions tab, click on the failed execution, and click the red-highlighted node. The error message appears in the node's output panel with details about what went wrong.

### How do I re-run a failed execution with the same data?

In the execution history, click on the failed execution, then click the Retry button. This re-runs the workflow with the same input data from the original execution.

### Can I get notified automatically when a workflow fails?

Yes. Create a separate workflow with an Error Trigger node as the start. Connect it to a notification node (Slack, email, etc.). The Error Trigger fires whenever any workflow in your n8n instance encounters an error.

### Why does my workflow work manually but fail when triggered?

Manual and triggered executions may receive different data. Manual runs use pinned data or simplified test data, while triggers receive real-world data that may have missing fields, different formats, or edge cases.

### How long are execution logs kept?

Configure retention with EXECUTIONS_DATA_PRUNE=true and EXECUTIONS_DATA_MAX_AGE (in hours). Default behavior varies by version. Set these explicitly to ensure failed executions are available for investigation.

### What should I do if I cannot find the error in n8n?

Enable N8N_LOG_LEVEL=debug, reproduce the error, then check the server logs for HTTP request details and internal errors that do not appear in the UI.

### Can RapidDev help me diagnose and fix persistent n8n errors?

Yes. RapidDev can audit your n8n workflows, identify error patterns, and implement robust error handling and monitoring. Contact RapidDev for a free consultation.

---

Source: https://www.rapidevelopers.com/n8n-tutorial/how-to-troubleshoot-n8n-errors
© RapidDev — https://www.rapidevelopers.com/n8n-tutorial/how-to-troubleshoot-n8n-errors