= $input.first().json;
const incident = {
incidentId: INC-${raw.execution.id},
workflowId: raw.workflow.id,
workflowName: raw.workflow.name,
failedNode: raw.execution.lastNodeExecuted || 'unknown',
errorMessage: raw.execution.error?.message || 'Unhandled termination',
errorStack: raw.execution.error?.stack || '',
errorType: raw.execution.error?.name || 'Error',
executionUrl: raw.execution.url,
isRetry: raw.execution.retryOf !== null,
retryDepth: raw.execution.retryOf ? 1 : 0,
timestamp: new Date().toISOString()
};
return [{ json: incident }];
**Architecture Rationale**: Normalization isolates expression logic from downstream routing. By explicitly mapping `retryOf` to a boolean flag and calculating `retryDepth`, you create deterministic conditions for retry policies. The `incidentId` prefix standardizes tracking across external systems like Slack, PagerDuty, or logging databases.
### Step 3: Implement Deterministic Routing Logic
Routing should prioritize severity, idempotency, and observability. A production handler typically branches into three paths: critical alerting, transient retry, and persistent logging.
**Critical Alerting Branch**: Route payment, billing, or data-pipeline workflows to high-priority channels.
```typescript
// Switch condition for critical routing
const criticalKeywords = ['payment', 'billing', 'ledger', 'sync'];
const isCritical = criticalKeywords.some(kw =>
$input.first().json.workflowName.toLowerCase().includes(kw)
);
return isCritical ? [true] : [false];
Transient Retry Branch: Automatically retry rate limits, timeouts, or 5xx responses. Enforce a maximum retry depth to prevent cascading failures.
// Safe retry condition
const retryablePatterns = ['timeout', 'rate limit', '503', '502', 'ETIMEDOUT'];
const isRetryable = retryablePatterns.some(p =>
$input.first().json.errorMessage.toLowerCase().includes(p)
);
const canRetry = !$input.first().json.isRetry && $input.first().json.retryDepth < 3;
return (isRetryable && canRetry) ? [true] : [false];
Persistent Logging Branch: All failures, regardless of routing, should be appended to an immutable store for trend analysis and compliance.
Architecture Rationale: Decoupling routing from alerting prevents alert fatigue. Transient errors are handled automatically without human intervention, while critical failures escalate immediately. Logging every event creates a historical dataset for identifying systemic API instability or recurring schema drift.
Pitfall Guide
| Pitfall | Explanation | Fix |
|---|
| Infinite Retry Cascades | A retried execution fails again, triggering the Error Trigger, which retries again. This creates a tight loop that exhausts API quotas and n8n execution limits. | Always check $json.execution.retryOf === null before initiating a retry. Implement a maximum retry depth counter and route exhausted retries to a dead-letter queue or manual review channel. |
| Handler Self-Termination | If the error handler workflow contains a bug (e.g., malformed expression, missing credential), it fails silently. n8n does not recursively trigger error handlers for handler failures. | Keep the handler workflow minimal. Use a separate test workflow with a deliberate throw new Error() to validate the handler independently. Implement a secondary watchdog that monitors handler execution logs. |
| Localhost URL Leakage | The execution.url field defaults to the internal host if the environment variable N8N_EDITOR_BASE_URL is unset. External alerting channels receive unreachable links. | Configure N8N_EDITOR_BASE_URL=https://your-public-domain.com in the n8n environment. Verify the URL resolves externally before deploying the handler. |
| Credential Hardcoding in Retry Calls | Developers embed API keys directly in HTTP Request node headers or expressions to call the n8n retry endpoint. This exposes secrets in execution logs and version control. | Store the n8n API key as a native credential. Reference it via the HTTP Request node's authentication dropdown. Never interpolate secrets into expression strings. |
| Unbounded Error Payloads | Large stack traces or deeply nested error objects consume memory and exceed webhook payload limits when forwarded to external APIs. | Sanitize the payload in the normalization step. Truncate stack traces to the first 500 characters. Strip internal metadata before routing to external systems. |
| Missing Activation State Dependency | The Error Trigger only fires if the handler workflow is active. Developers often build and test handlers in draft mode, then forget to activate them before production assignment. | Add a pre-deployment validation step that checks workflow status via the n8n REST API. Implement a CI/CD gate that blocks source workflow assignment if the handler is inactive. |
| Cross-Workflow Context Blind Spots | The Error Trigger provides execution metadata but does not include the original input data that caused the failure. Debugging requires manual navigation to the execution UI. | If input context is critical, implement a pre-failure logging step in source workflows that writes input snapshots to a temporary store. Reference the execution ID in the error handler to fetch context on demand. |
Production Bundle
Action Checklist
Decision Matrix
| Scenario | Recommended Approach | Why | Cost Impact |
|---|
| High-volume transactional workflows (payments, orders) | Critical routing + PagerDuty + Postgres audit log | Zero tolerance for silent failures; requires immediate escalation and immutable records | Moderate (higher alerting tier, dedicated DB writes) |
| External API ingestion pipelines | Transient retry + Slack warnings + Sheets log | Rate limits and timeouts are expected; automated recovery reduces manual intervention | Low (reuses existing messaging channels, minimal DB overhead) |
| Internal data sync / ETL jobs | Logging only + weekly digest | Failures are non-urgent; batch correction is acceptable | Minimal (append-only storage, no real-time alerting) |
| Development / staging environments | Console logging + email digest | Prevents alert fatigue during active iteration; preserves debugging context | None (uses built-in n8n logging) |
Configuration Template
The following JSON defines a production-ready failure router. It normalizes payloads, routes critical failures to Slack, retries transient errors via the n8n API, and persists all events to Postgres. Import via Menu → Import from JSON.
{
"name": "sys: failure-router",
"nodes": [
{
"parameters": {},
"id": "trigger-err-01",
"name": "Error Trigger",
"type": "n8n-nodes-base.errorTrigger",
"typeVersion": 1,
"position": [240, 300]
},
{
"parameters": {
"jsCode": "const raw = $input.first().json;\nconst incident = {\n incidentId: `INC-${raw.execution.id}`,\n workflowId: raw.workflow.id,\n workflowName: raw.workflow.name,\n failedNode: raw.execution.lastNodeExecuted || 'unknown',\n errorMessage: raw.execution.error?.message || 'Unhandled termination',\n errorStack: (raw.execution.error?.stack || '').slice(0, 500),\n errorType: raw.execution.error?.name || 'Error',\n executionUrl: raw.execution.url,\n isRetry: raw.execution.retryOf !== null,\n retryDepth: raw.execution.retryOf ? 1 : 0,\n timestamp: new Date().toISOString()\n};\nreturn [{ json: incident }];"
},
"id": "norm-01",
"name": "Normalize Payload",
"type": "n8n-nodes-base.code",
"typeVersion": 2,
"position": [460, 300]
},
{
"parameters": {
"conditions": {
"string": [
{
"value1": "={{ $json.workflowName.toLowerCase() }}",
"operation": "contains",
"value2": "payment"
},
{
"value1": "={{ $json.workflowName.toLowerCase() }}",
"operation": "contains",
"value2": "billing"
}
]
},
"combineOperation": "any"
},
"id": "route-crit-01",
"name": "Is Critical?",
"type": "n8n-nodes-base.if",
"typeVersion": 1,
"position": [680, 200]
},
{
"parameters": {
"conditions": {
"string": [
{
"value1": "={{ $json.errorMessage.toLowerCase() }}",
"operation": "contains",
"value2": "timeout"
},
{
"value1": "={{ $json.errorMessage.toLowerCase() }}",
"operation": "contains",
"value2": "rate limit"
}
]
},
"combineOperation": "any"
},
"id": "route-retry-01",
"name": "Is Retryable?",
"type": "n8n-nodes-base.if",
"typeVersion": 1,
"position": [680, 400]
},
{
"parameters": {
"channelId": { "value": "SLACK_CRITICAL_CHANNEL_ID" },
"text": "=🚨 *Critical Failure*\nWorkflow: {{ $json.workflowName }}\nError: {{ $json.errorMessage }}\nNode: {{ $json.failedNode }}\nDebug: {{ $json.executionUrl }}"
},
"id": "alert-crit-01",
"name": "Slack Critical",
"type": "n8n-nodes-base.slack",
"typeVersion": 2.2,
"position": [900, 100]
},
{
"parameters": {
"method": "POST",
"url": "={{ 'https://your-n8n-instance.com/api/v1/executions/' + $json.incidentId.replace('INC-', '') + '/retry' }}",
"authentication": "predefinedCredentialType",
"nodeCredentialType": "n8nApi",
"sendHeaders": true,
"headerParameters": {
"parameters": [
{ "name": "Content-Type", "value": "application/json" }
]
}
},
"id": "exec-retry-01",
"name": "Retry Execution",
"type": "n8n-nodes-base.httpRequest",
"typeVersion": 4.2,
"position": [900, 400]
},
{
"parameters": {
"operation": "insert",
"schema": "public",
"table": "workflow_incidents",
"columns": "incident_id, workflow_id, workflow_name, failed_node, error_message, error_type, execution_url, is_retry, retry_depth, timestamp",
"additionalFields": {
"inputDataFieldName": "json"
}
},
"id": "log-pg-01",
"name": "Log to Postgres",
"type": "n8n-nodes-base.postgres",
"typeVersion": 2.5,
"position": [900, 600]
}
],
"connections": {
"Error Trigger": { "main": [[{ "node": "Normalize Payload", "type": "main", "index": 0 }]] },
"Normalize Payload": { "main": [[{ "node": "Is Critical?", "type": "main", "index": 0 }], [{ "node": "Is Retryable?", "type": "main", "index": 0 }]] },
"Is Critical?": { "main": [[{ "node": "Slack Critical", "type": "main", "index": 0 }], [{ "node": "Log to Postgres", "type": "main", "index": 0 }]] },
"Is Retryable?": { "main": [[{ "node": "Retry Execution", "type": "main", "index": 0 }], [{ "node": "Log to Postgres", "type": "main", "index": 0 }]] }
}
}
Quick Start Guide
- Create the handler: Import the Configuration Template JSON into your n8n instance. Rename it to
sys: failure-router and activate it.
- Configure credentials: Attach your n8n API credential to the
Retry Execution node. Verify N8N_EDITOR_BASE_URL is set in your environment variables.
- Assign to source workflows: Open any production workflow, navigate to Settings → Error Workflow, and select
sys: failure-router. Save the workflow.
- Validate routing: Create a temporary workflow with a single Code node containing
throw new Error('validation-test'). Assign the handler, activate the test workflow, and run it. Confirm Slack alert, Postgres log, and execution URL resolution.
- Monitor: Check the n8n executions dashboard to verify the handler processes the synthetic failure without errors. Remove the test workflow once validation succeeds.
Centralized error routing transforms n8n from a fragile automation tool into a resilient execution platform. By intercepting termination events, normalizing context, and applying deterministic routing policies, you eliminate silent failures, reduce incident response time, and establish a consistent observability layer across your entire workflow ecosystem.
