Complete Guide for n8n Node Errors
Introduction
n8n workflows consist of interchangeable nodes, each capable of emitting runtime errors. This guide is for workflow designers, DevOps engineers, and integration specialists who need a high‑level map of n8n node errors and want to know where to start investigating when something goes wrong. It outlines the core error‑handling architecture, groups common node‑specific failure modes, describes a universal debugging workflow, and points you to dedicated deep‑dive pages for every individual node error. Detailed fixes live in those child guides this page remains a roadmap, not a solution manual.
1. n8n error‑handling architecture (overview)
| Mechanism | Purpose | Where to learn more |
|---|---|---|
| Error Trigger node | Catches uncaught exceptions downstream and can launch an alternative error workflow | Error Trigger node not catching errors |
| Continue on Fail flag | Allows a node to fail without aborting the entire workflow | — |
| Error Workflow | Separate flow that runs when any node reports an error, useful for alerts or rollbacks | — |
These layers separate detection (the failing node) from response (the workflow’s reaction).
2. Common categories of node‑specific errors
| Category | Typical symptom | Example child guides |
|---|---|---|
| Authentication / credential errors | 401 Unauthorized, OAuth token refresh failures | • HTTP Request node 401 error • Google Sheets node authentication failure • MySQL node authentication error • SMTP node authentication error • Slack node permission denied |
| Timeouts & limits | Operations abort after a preset period or exceed API rate limits | • HTTP Request node timeout • Wait node timeout • Split in Batches node limit exceeded • Google Sheets node rate limit • Slack node rate limit |
| Data‑type or schema mismatches | “Type mismatch”, “Invalid field”, “Reference undefined” | • Set node type mismatch error • Merge node type mismatch • Function node reference error |
| Configuration / syntax errors | Invalid JSON, malformed JavaScript, bad URL format | • Function node syntax error • Webhook node invalid URL • Execute Command node invalid command error |
| External‑service failures | API throttling, file corruption, network drops | • SMTP node send failure • Excel node file corrupted error |
| Logic / evaluation problems | Unexpected IF results, merge conflicts | • IF node conditional evaluation error • Merge node conflict error |
Use this table to quickly narrow the search space before opening a node‑specific guide.
3. General debugging workflow for any node
- Identify the failing node – the execution log highlights the node with a red “error” badge.
- Read the high‑level error message – n8n surfaces the error class (e.g., AuthenticationError, TimeoutError).
- Map the error to a category using the table above.
- Open the matching child guide for that node and error type.
- Apply the node‑specific remediation (found in the child guide) and re‑run the workflow.
When the error relates to built‑in mechanisms (continue‑on‑fail, error workflow, or error trigger), adjust those settings in the Workflow Settings panel rather than the node itself.
4. Built‑in error handling features
| Feature | When to use it | What it covers |
|---|---|---|
| Continue on Fail | Non‑critical nodes where downstream steps can still succeed | Prevents a single node’s exception from aborting the whole workflow. |
| Error Trigger node | Centralized error collection, alerting, or compensation logic | Captures any uncaught error downstream and starts a separate error workflow. |
| Error Workflow | Organization‑wide policies (e.g., Slack alerts, ticket creation) | Runs automatically when a node reports an error, regardless of the original workflow’s state. |
| Retry on Failure (available on many nodes) | Transient network glitches or rate‑limit responses | Automatically re‑executes the node a configurable number of times before surfacing the error. |
For edge cases where the Error Trigger itself does not fire, see the child article Error Trigger node not catching errors.
5. Best practices for reducing node failures
- Validate credentials early – add a lightweight test step before the main workflow runs.
- Set sensible timeouts – keep node timeout values higher than the typical API response time.
- Enable retry logic – use “Retry on Failure” for flaky external services.
- Normalize data types – insert a Set node after transformations to enforce the expected schema.
- Version‑control custom code – store Function/Code node scripts in a repository and reference them, avoiding accidental syntax drift.
- Monitor rate limits – for APIs with strict quotas (Google Sheets, Slack, etc.), insert a Wait node or batch‑splitting strategy to stay under limits.
These guidelines lower the chance of encountering the specific errors documented in the child pages.
6. Detailed node‑error guides (quick navigation)
HTTP & Webhook nodes
- HTTP Request node 401 error
- HTTP Request node timeout
- Webhook node invalid URL error
- Webhook node missing signature
Function / Code nodes
Data manipulation nodes
- Set node type mismatch error
- Split in Batches node limit exceeded
- Merge node conflict error
- Merge node type mismatch
Third‑party integration nodes
- Google Sheets node authentication failure
- Google Sheets node rate limit error
- MySQL node connection timeout
- MySQL node authentication error
- SMTP node send failure
- SMTP node authentication error
- Slack node permission denied
- Slack node rate limit error
Control‑flow nodes
Miscellaneous nodes
- Execute Command node invalid command error
- Excel node file corrupted error
- Error Trigger node not catching errors
Internal linking summary
| Group | Child pages |
|---|---|
| HTTP & Webhook | HTTP Request 401, HTTP Request timeout, Webhook invalid URL, Webhook missing signature |
| Function / Code | Function syntax, Function reference, Code runtime |
| Data manipulation | Set type mismatch, Split in Batches limit, Merge conflict, Merge type mismatch |
| Integrations | Google Sheets auth, Google Sheets rate limit, MySQL timeout, MySQL auth, SMTP send, SMTP auth, Slack permission, Slack rate limit |
| Control flow | IF conditional, Wait timeout |
| Other | Execute Command invalid, Excel file corruption, Error Trigger catch‑all |
These grouped links reinforce crawl efficiency and ensure that link equity flows from the pillar to each specialized guide.
This pillar page provides the map; each linked child page contains the detailed diagnostics and remediation steps.
