n8n Error Trigger: The Complete Guide With a Ready Error Workflow

The n8n Error Trigger is the node that starts an error workflow: when a production execution of a linked workflow fails, n8n runs the workflow that contains the Error Trigger and passes it one item describing the failure. That item holds the failed workflow's name and ID, the error message and stack, the last node that ran, the execution mode and, when the run was saved, a link straight to the failed execution.

Checked October 2026 against n8n's docs for the Error Trigger, error workflows, workflow settings and saving and publishing, and against the source code of n8n 2.42.6, the latest stable release on 9 October 2026. Where the docs and the code disagree, this guide says which is which.

This is the node-level reference in our n8n hub. Retries, On Error settings and backoff loops live in the wider n8n error handling guide. This page stays on the trigger itself: how it gets called, what every field in its output means, a handler you can import, and why it sometimes says nothing at all.

What is the n8n Error Trigger node?

The Error Trigger is a trigger node with no parameters. It does not poll or listen. n8n's execution engine calls it when another workflow's run fails, and a workflow can hold only one. Five behaviours define it:

• It is linked from the failing side. You pick the handler in the failing workflow's Settings, under Error Workflow. One handler can serve any number of workflows.
• A workflow can handle itself. The docs note that a workflow containing an Error Trigger uses itself as its error workflow by default.
• Production runs only. The docs are blunt: "You can't test error workflows when running workflows manually." Only runs started by a schedule, webhook, app event or retry dispatch it.
• The handler run is its own execution. n8n saves it under the handler workflow with the mode error, so the handler's Executions tab shows every alert that was attempted.
• It is free to run. n8n's executions docs list error workflow executions among the runs that do not count toward a plan's quota.

How do you set up the n8n Error Trigger?

Build the handler once, publish it, then point each production workflow at it. Most of the work is deciding where alerts should land.

You can read this in the code. loadErrorWorkflowData in workflow-execution.service.ts returns nothing when the handler has no published version, and n8n's own validation service describes "the three ways a link silently never fires: the target is gone, unpublished, or has no Error Trigger". The same check has been in place since the 2.0.0 release.

What data does the n8n Error Trigger receive?

One item, in one of two shapes. When a node fails during a run, you get an execution object and a workflow object. This is n8n's documented example:

[
  {
    "execution": {
      "id": "231",
      "url": "https://n8n.example.com/execution/231",
      "retryOf": "34",
      "error": {
        "message": "Example Error Message",
        "stack": "Stacktrace"
      },
      "lastNodeExecuted": "Node With Error",
      "mode": "manual"
    },
    "workflow": {
      "id": "1",
      "name": "Example Workflow"
    }
  }
]

Here is every field, when it exists and what to do with it:

Four details the example does not show:

• The real link is longer. In the 2.42.6 source, execute-error-workflow.ts builds execution.url as the instance base URL plus /workflow/<workflowId>/executions/<executionId>. Treat it as an opaque link and read IDs from execution.id and workflow.id, not from the URL.
• The error object can carry more. The docs promise message and stack. n8n's error classes also define name (for example NodeApiError or NodeOperationError), description, timestamp, context, node and, on API errors, httpCode. None of these are documented for the Error Trigger, so read them with a fallback.
• manual is sample data. A real payload never has that mode, because manual runs do not dispatch the handler. Expect trigger for schedules, polling and app events, webhook for Webhook calls, and retry when someone retried a failed run.
• Newer builds add execution.executionContext. It is internal run metadata (a version, a start time, a source). It is not in the docs, so do not build alerts on it.

The second shape: when the trigger node itself fails

If the failure happens in the main workflow's trigger node, no execution exists yet. The docs say the item then has "less information in execution and more in trigger":

{
  "trigger": {
    "error": {
      "context": {},
      "name": "WorkflowActivationError",
      "cause": { "message": "", "stack": "" },
      "timestamp": 1654609328787,
      "message": "",
      "node": { }
    },
    "mode": "trigger"
  },
  "workflow": { "id": "", "name": "" }
}

This is the shape that breaks naive handlers. An alert that reads {{ $json.execution.error.message }} throws on a trigger failure, the handler run fails, and you hear nothing about the one error that stops a workflow from starting at all. Every handler should read both shapes, which is what the Code node in the template below does.

n8n error workflow template: import-ready JSON

This handler has three nodes: the Error Trigger, a Code node that turns both payload shapes into the same flat fields, and an HTTP Request node that posts the alert to a chat webhook. It needs no credential, so it works as soon as you paste one URL. Node types, versions and parameter names come from the n8n 2.42.6 source.

{
  "name": "Error Handler (webhook alert)",
  "nodes": [
    {
      "parameters": {},
      "id": "c3a8e4b1-0001-4e2d-9a3c-000000000001",
      "name": "Error Trigger",
      "type": "n8n-nodes-base.errorTrigger",
      "typeVersion": 1,
      "position": [
        0,
        0
      ]
    },
    {
      "parameters": {
        "jsCode": "const data = $input.first().json;\nconst run = data.execution ?? {};\nconst trig = data.trigger ?? {};\nconst error = run.error ?? trig.error ?? {};\n\nreturn [{\n  json: {\n    workflowName: data.workflow?.name ?? 'Unknown workflow',\n    workflowId: data.workflow?.id ?? '',\n    source: data.execution ? 'execution' : 'trigger',\n    failedNode: run.lastNodeExecuted ?? error.node?.name ?? 'Trigger node',\n    errorName: error.name ?? 'Error',\n    message: error.message || error.description || 'No error message',\n    mode: run.mode ?? trig.mode ?? '',\n    executionId: run.id ?? '',\n    executionUrl: run.url ?? '',\n    isRetry: Boolean(run.retryOf),\n  },\n}];"
      },
      "id": "c3a8e4b1-0002-4e2d-9a3c-000000000002",
      "name": "Normalise error",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [
        220,
        0
      ]
    },
    {
      "parameters": {
        "method": "POST",
        "url": "https://hooks.slack.com/services/REPLACE/WITH/YOUR-WEBHOOK",
        "sendBody": true,
        "bodyParameters": {
          "parameters": [
            {
              "name": "text",
              "value": "={{ $json.workflowName }} failed at {{ $json.failedNode }}\n{{ $json.errorName }}: {{ $json.message }}\nMode: {{ $json.mode }}{{ $json.isRetry ? ' (this run was a retry)' : '' }}\n{{ $json.executionUrl || 'No saved execution: check the trigger node' }}"
            }
          ]
        },
        "options": {}
      },
      "id": "c3a8e4b1-0003-4e2d-9a3c-000000000003",
      "name": "Send alert",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        440,
        0
      ],
      "retryOnFail": true,
      "maxTries": 3,
      "waitBetweenTries": 2000
    }
  ],
  "connections": {
    "Error Trigger": {
      "main": [
        [
          {
            "node": "Normalise error",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Normalise error": {
      "main": [
        [
          {
            "node": "Send alert",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "settings": {
    "executionOrder": "v1"
  }
}

1. Import it. Copy the JSON, open a new workflow and paste it onto the canvas (Ctrl+V or Cmd+V). The export and import docs also describe Import from File in the workflow menu.
2. Set the URL. Open Send alert and replace the placeholder with your own. The body sends one field named text, which is what a Slack incoming webhook expects. Other chat tools use a different field name, so rename it to match theirs.
3. Test the message. Select Execute workflow. The Error Trigger returns its sample item and the alert should arrive.
4. Publish, then link. Publish the handler and select it as the Error Workflow in each workflow you want covered.

Two notes on the design. The alert node retries three times, two seconds apart, because a lost alert is the one failure nobody reports. And Slack's docs warn that a webhook URL contains a secret: anyone who can open the workflow can post to that channel. If that matters on your instance, swap the HTTP Request for the Slack or Send Email node, which keep the secret in a credential.

How do you test an n8n Error Trigger?

In two passes, because the sample data and a real failure prove different things. First, open the handler and run the Error Trigger with Execute step. In a manual run with no input, the node returns built-in sample data, which is enough to shape the message.

Second, cause a real failure without touching a real workflow:

1. Create a workflow with a Schedule Trigger set to every minute, connected to a Stop and Error node with the message Error Trigger test.
2. In its Settings, select your handler as the Error Workflow.
3. Publish it and wait one minute. Expected result: an alert naming this workflow, the Stop and Error node and your message, with a working link.
4. Unpublish and delete the test workflow.

If you need a different interval for the test, our n8n cron expression generator builds the expression. Webhook-started workflows are just as easy to break on purpose: call the production URL described in the n8n webhook guide with a payload your workflow rejects.

Why is the n8n Error Trigger not firing?

Almost always for one of seven reasons, and none of them show an error in the editor. Start with the handler's own Executions tab: an empty list means n8n never started it, and a failed run there means it started and was blocked or broke.

Two rows need a source. The permission block comes from the same caller policy that guards sub-workflows: its default only allows callers in the same project, and a blocked call is saved in the handler as a failed execution. The DEFAULT row is reported in issue 40824, open in October 2026: clearing the setting stores the literal value DEFAULT, and the dispatch code in 2.42.6 treats any stored value as a workflow ID, so the workflow's own Error Trigger is skipped.

An error workflow also cannot report what n8n never sees. If the instance is down or a schedule silently stops, there is no failed execution to dispatch. Watch the instance from outside as well; our n8n self-hosting guide covers the health checks.

One shared handler, or an Error Trigger in every workflow?

Use one shared handler for alerts, and add an Error Trigger inside a workflow only when that workflow needs its own cleanup. The shared handler is one place to change a channel, one thing to publish and one execution list to audit.

Cleanup means work that belongs to one process: releasing a lock row, marking an order as failed, telling a customer their export did not finish. Alerts do not belong there. If these workflows are becoming a product people pay for, our AI SaaS Builder program covers the same discipline in application code: production error handling, rate limits and fallbacks for Claude API features.

Error Trigger pre-flight checklist

Once this is in place, the plan your instance runs on matters less than you might expect, because handler runs are not billed; our n8n pricing guide explains what is.

n8n Error Trigger: FAQ