Error Handling in n8n: Error Workflows und Fehler-Benachrichtigungen

Ein Error Workflow ist in n8n eine gewöhnliche Automatisierung, die automatisch startet, sobald ein anderer Workflow fehlschlägt. Sie hinterlegen ihn in den Workflow-Einstellungen im Feld „Error Workflow" und beginnen ihn mit dem Error Trigger Node.

Zusammen mit der Einstellung „Retry On Fail" einzelner Nodes und einer Benachrichtigung per E-Mail oder Microsoft Teams gehen Fehler nicht mehr stillschweigend unter. Dieser Artikel zeigt den Aufbau, die gelieferten Fehlerdaten und die Ausdrücke für den Benachrichtigungstext.

Was ist ein Error Workflow und wann greift er?

Ein Error Workflow ist ein separater Workflow mit dem Error Trigger als erster Node, der bei einer fehlgeschlagenen Ausführung eines anderen Workflows startet. Typischer Zweck laut Dokumentation sind E-Mail- oder Slack-Benachrichtigungen im Fehlerfall.

Ein einzelner Error Workflow lässt sich für beliebig viele produktive Workflows hinterlegen. Sie brauchen also nicht für jede Automatisierung eine eigene Fehlerbehandlung.

Zwei Punkte sind dabei wichtig. Erstens muss ein Workflow, der nur über den Error Trigger startet, nicht veröffentlicht werden. Zweitens lässt sich ein Error Workflow nicht durch manuelles Ausführen testen, denn der Error Trigger reagiert ausschließlich auf automatische Ausführungen.

Enthält ein Workflow selbst einen Error Trigger, nutzt er sich laut Dokumentation zum Error Trigger Node standardmäßig selbst als Error Workflow. Weitere Grundlagen stehen in der n8n-Dokumentation zur Fehlerbehandlung.

Wie richten Sie einen Error Workflow ein?

Die Einrichtung besteht aus zwei Teilen: Sie bauen den Handler-Workflow und weisen ihn danach dem zu überwachenden Workflow zu.

1. Neuen Workflow anlegen, den Error Trigger als erste Node setzen, den Workflow etwa „Error Handler" nennen und speichern.
2. Den zu überwachenden Workflow öffnen und oben rechts über das Drei-Punkte-Menü die Settings aufrufen.
3. Im Feld Error Workflow (to notify when this one errors) den Handler auswählen und speichern.

Die vollständige Liste der Workflow-Einstellungen steht in der Dokumentation zu den Workflow-Einstellungen.

Der folgende JSON-Ausschnitt lässt sich über „Import from File" oder „Import from URL" direkt in n8n einfügen. Er enthält den Error Trigger und eine Send-Email-Node.

1{
2  "name": "Error Handler",
3  "nodes": [
4    {
5      "parameters": {},
6      "name": "Error Trigger",
7      "type": "n8n-nodes-base.errorTrigger",
8      "typeVersion": 1,
9      "position": [0, 0]
10    },
11    {
12      "parameters": {
13        "fromEmail": "n8n@beispiel.de",
14        "toEmail": "technik@beispiel.de",
15        "subject": "=n8n-Fehler: {{ $json.workflow.name }}",
16        "emailFormat": "text",
17        "text": "=Workflow: {{ $json.workflow.name }}\nFehler: {{ $json.execution?.error?.message ?? $json.trigger?.error?.message }}\nLetzte Node: {{ $json.execution?.lastNodeExecuted ?? 'keine' }}\nAusfuehrung: {{ $json.execution?.url ?? 'nicht gespeichert' }}"
18      },
19      "name": "Send Email",
20      "type": "n8n-nodes-base.emailSend",
21      "typeVersion": 2.1,
22      "position": [220, 0]
23    }
24  ],
25  "connections": {
26    "Error Trigger": {
27      "main": [[{ "node": "Send Email", "type": "main", "index": 0 }]]
28    }
29  }
30}
Copy

Nach dem Import hinterlegen Sie in der Send-Email-Node noch die SMTP-Zugangsdaten. Für einen Teams-Kanal tauschen Sie die Node gegen die Microsoft-Teams-Node und behalten die Ausdrücke bei.

Welche Daten liefert der Error Trigger?

Der Error Trigger übergibt ein JSON-Objekt mit zwei Zweigen: execution beschreibt die gescheiterte Ausführung, workflow den betroffenen Workflow. Die Dokumentation nennt folgendes Beispiel:

1[
2  {
3    "execution": {
4      "id": "231",
5      "url": "https://n8n.example.com/execution/231",
6      "retryOf": "34",
7      "error": {
8        "message": "Example Error Message",
9        "stack": "Stacktrace"
10      },
11      "lastNodeExecuted": "Node With Error",
12      "mode": "manual"
13    },
14    "workflow": {
15      "id": "1",
16      "name": "Example Workflow"
17    }
18  }
19]
Copy

Nicht jedes Feld ist in jedem Fehlerfall gefüllt. Die folgende Übersicht zeigt, worauf Sie sich verlassen können.

Feld | Inhalt | Immer vorhanden

Feld: execution.id · Inhalt: Kennung der fehlgeschlagenen Ausführung · Immer vorhanden: nein, nur bei gespeicherter Ausführung

Feld: execution.url · Inhalt: Direktlink zur Ausführung · Immer vorhanden: nein, nur bei gespeicherter Ausführung

Feld: execution.error.message · Inhalt: Fehlermeldung im Klartext · Immer vorhanden: ja

Feld: execution.error.stack · Inhalt: Stack Trace · Immer vorhanden: ja

Feld: execution.lastNodeExecuted · Inhalt: Node, an der es gescheitert ist · Immer vorhanden: ja

Feld: execution.mode · Inhalt: Modus der Ausführung, etwa manual · Immer vorhanden: ja

Feld: execution.retryOf · Inhalt: Kennung der ursprünglichen Ausführung · Immer vorhanden: nein, nur bei Wiederholungen

Feld: workflow.id, workflow.name · Inhalt: betroffener Workflow · Immer vorhanden: ja

Scheitert bereits der Trigger-Node der Hauptautomatisierung, sieht die Struktur anders aus. Dann liefert n8n statt execution einen Zweig trigger mit trigger.error.message und trigger.mode.

Deshalb greifen die Ausdrücke oben mit optionaler Verkettung zu. Der Operator ?. verhindert einen Absturz, wenn execution fehlt, und ?? liefert den Ersatzwert.

1{{ $json.execution?.error?.message ?? $json.trigger?.error?.message ?? 'unbekannter Fehler' }}
Copy

Zusätzlich können Sie mit der Stop-And-Error-Node einen Fehler bewusst erzwingen, etwa bei einer unplausiblen Datenlage. Die Node kennt die Typen „Error Message" und „Error Object".

Retry On Fail oder Error Workflow: Was greift wann?

Beide Mechanismen arbeiten auf verschiedenen Ebenen und ergänzen sich. Retry On Fail wiederholt eine einzelne Node, der Error Workflow reagiert erst auf die endgültig gescheiterte Ausführung.

Einstellung | Wirkt auf | Greift wann | Ergebnis

Einstellung: Retry On Fail · Wirkt auf: einzelne Node · Greift wann: direkt nach einem gescheiterten Versuch · Ergebnis: Aufruf wird in derselben Ausführung wiederholt

Einstellung: On Error: Stop Workflow · Wirkt auf: einzelne Node · Greift wann: wenn alle Versuche gescheitert sind · Ergebnis: Ausführung bricht ab, Error Workflow startet

Einstellung: On Error: Continue · Wirkt auf: einzelne Node · Greift wann: wenn alle Versuche gescheitert sind · Ergebnis: Workflow läuft mit den letzten gültigen Daten weiter

Einstellung: On Error: Continue (using error output) · Wirkt auf: einzelne Node · Greift wann: wenn alle Versuche gescheitert sind · Ergebnis: Fehlerdaten laufen in einen zweiten Ausgang

Einstellung: Error Workflow · Wirkt auf: gesamte Ausführung · Greift wann: bei endgültigem Fehlschlag · Ergebnis: separater Workflow benachrichtigt oder eskaliert

Retry On Fail aktivieren Sie in der jeweiligen Node unter Settings. Über Max Tries legen Sie die Zahl der Versuche fest, über Wait Between Tries (ms) die Pause dazwischen.

Bei Diensten mit Rate Limits empfiehlt die Dokumentation zum Umgang mit API-Rate-Limits, die Wartezeit über das Limit-Intervall zu legen. Erlaubt eine API eine Anfrage pro Sekunde, setzen Sie den Wert auf 1000.

Beachten Sie die Voreinstellung: „Continue" verhindert den Abbruch und damit auch den Start des Error Workflows. Wer benachrichtigt werden will, belässt kritische Nodes auf „Stop Workflow".

Wer eine bestehende n8n-Umgebung mit Error Workflows, Retry-Strategien und Benachrichtigungen absichern lassen möchte, findet Unterstützung bei den n8n-Leistungen von NordFlux.

Typische Fehler und Ursachen

Fünf Fehlerbilder treten beim Aufbau von Error Workflows besonders oft auf.

Der Error Workflow startet nie, obwohl der Workflow sichtbar fehlschlägt.

Ursache: Er ist in den Workflow-Einstellungen nicht zugewiesen, oder der Fehlschlag stammt aus einem manuellen Testlauf. Lösung: Zuweisung prüfen und den Fehler in einer automatischen Ausführung erzeugen. Quelle: Error Trigger Node.

Die Benachrichtigung enthält keinen Link zur Ausführung.

Ursache: Der Fehler liegt im Trigger-Node der Hauptautomatisierung, daher fehlen execution.id und execution.url. Lösung: einen Ersatztext über ?? setzen und zusätzlich trigger.error.message auswerten. Quelle: Fehler abfangen.

Der Error Workflow scheitert selbst an „Cannot read properties of undefined".

Ursache: Der Ausdruck greift fest auf $json.execution zu, im Trigger-Fehlerfall existiert aber nur $json.trigger. Lösung: alle Zugriffe mit ?. schreiben. Quelle: Fehler abfangen.

Ein Workflow meldet sich selbst statt an den zentralen Handler.

Ursache: Der Workflow enthält selbst einen Error Trigger und nutzt sich deshalb standardmäßig als eigenen Error Workflow. Lösung: den Error Trigger entfernen oder den zentralen Handler ausdrücklich zuweisen. Quelle: Error Trigger Node.

Eine Node scheitert weiter an Rate Limits, obwohl Retry On Fail aktiv ist.

Ursache: „Wait Between Tries" liegt unter dem Intervall der API. Lösung: die Wartezeit über das Limit setzen oder auf Loop Over Items und Wait ausweichen. Quelle: API-Rate-Limits.

Häufige Fragen zu Error Handling in n8n

Brauche ich für jeden Workflow einen eigenen Error Workflow?

Nein. Ein einzelner Error Workflow lässt sich in den Einstellungen beliebig vieler Workflows hinterlegen. Für besonders kritische Prozesse können Sie zusätzlich einen spezialisierten Handler mit eigener Eskalationslogik anlegen.

Kann ich einen Error Workflow manuell testen?

Nein. Laut Dokumentation reagiert der Error Trigger nur, wenn eine automatische Ausführung fehlschlägt. Um das Verhalten trotzdem zu prüfen, erzwingen Sie in einem Testworkflow mit der Stop-And-Error-Node einen Fehler.

Was ist der Unterschied zwischen Retry On Fail und einem Error Workflow?

Retry On Fail wiederholt eine einzelne Node innerhalb derselben Ausführung. Der Error Workflow greift erst, wenn die gesamte Ausführung endgültig gescheitert ist. Retries fangen kurze Störungen ab, der Error Workflow informiert Menschen.

Muss der Error-Handler-Workflow aktiviert oder veröffentlicht sein?

Nein. Ein Workflow, der ausschließlich über den Error Trigger startet, muss laut Dokumentation nicht veröffentlicht werden. Er wird aufgerufen, sobald ein anderer Workflow ihn in seinen Einstellungen referenziert und selbst fehlschlägt.