n8n 3.0: Fünf Dinge, die der Migration Report dir nicht sagt

Wer n8n selbst betreibt, musste die Breaking Changes für 3.0 bisher von Hand gegen die eigene Instanz halten. Das ist vorbei: Unter Settings → Migration report liefert n8n inzwischen eine eigene Analyse. Sie listet betroffene Workflows und Instanz-Einstellungen, und die Breaking-Changes-Seite verweist an sieben Stellen darauf.

Die gute Nachricht: Der Report ist deutlich besser, als die Dokumentation vermuten lässt. Die schlechte: Er hat Lücken, und eine davon betrifft genau den Punkt, der deine Instanz nach dem Upgrade nicht mehr hochkommen lässt.

Ich habe das nicht geglaubt, sondern gemessen. Für diesen Artikel liefen drei n8n-Versionen lokal in Docker — 2.44.7, 2.46.0 und 3.0.0 — auf derselben Datenbank mit elf präparierten Workflows, die zusammen neun dokumentierte Fallstricke enthalten.

Der Stand am 27. Oktober 2026

Bevor es losgeht, der Versionsstand zum Zeitpunkt dieses Artikels — und der ist unübersichtlicher, als man erwarten würde:

• Das Docker-Image n8nio/n8n:3.0.0 existiert und ist lauffähig. Es wurde am 27.10.2026 um 08:36 UTC veröffentlicht.
• Der Tag latest zeigt weiterhin auf die 2er-Linie, und ein GitHub-Release für 3.0.0 gibt es nicht.
• Die Instanz, die aus diesem Image startet, bezeichnet sich im Browser-Titel selbst als n8n[RC] — Release Candidate.
• Die Breaking-Changes-Seite nennt kein Release-Datum mehr, nur noch „n8n 3.0 is releasing soon".
• Auf der 2er-Linie ist 2.44.7 stable, 2.46.0 ist Beta.

3.0.0 ist also gebaut, aber nicht freigegeben. Für dich heißt das: Du hast noch Zeit — aber du kannst das Upgrade heute schon testen, und genau das solltest du tun.

Zuerst der schnelle Weg: den Report laufen lassen

Bevor du irgendetwas von Hand prüfst, öffne Settings → Migration report. Der Punkt ist in der Community Edition vorhanden, nicht lizenzpflichtig.

Der Report nennt die Zielversion beim Namen, zählt kompatible Workflows und gruppiert die Befunde nach Auswirkung — „Executions will fail", „Behavior changes", „Capability removed". Auf meiner Testinstanz: zwölf Workflow-Befunde, neun von elf Workflows betroffen.

Interessanter ist der zweite Reiter. Der Report prüft nämlich nicht nur Workflows, sondern auch Instanz-Einstellungen:

Das ist mehr, als die Dokumentation verspricht. Sechs Instanz-Befunde, darunter zwei, die in jeder Upgrade-Checkliste als „stille Killer" geführt werden: der auf 60 Sekunden gesenkte Task-Timeout und der entfallende Binärdaten-Modus default. Beide meldet der Report von sich aus, obwohl die Breaking-Changes-Seite bei keinem von beiden auf ihn verweist.

Wer also eine Anleitung liest, die dir erklärt, wie du per CLI und jq alle Node-Typen aus deiner Datenbank ziehst: Das brauchst du für diese Punkte nicht mehr. Der Report macht das.

Für den Rest schon.

Die fünf Dinge, die er nicht abfängt

1. binaryData und storage nebeneinander — die Instanz startet nicht mehr

n8n 3.0 benennt das Verzeichnis ~/.n8n/binaryData in ~/.n8n/storage um. Existieren beide, rät n8n nicht, sondern bricht ab.

Das klingt nach einem Randfall, ist aber keiner: Betroffen ist jede Instanz, die ein Volume gezielt auf binaryData gemountet hat — die gängige Empfehlung aus älteren Setup-Anleitungen. Nach dem Upgrade liegt dann das alte, gemountete Verzeichnis neben dem neuen, das n8n selbst angelegt hat.

Ich habe genau das nachgestellt: ein Volume, in dem beide Verzeichnisse liegen, darauf 3.0.0 gestartet. Ergebnis:

StoragePathError: Both /home/node/.n8n/binaryData and /home/node/.n8n/storage
exist, so n8n cannot tell which one holds your data. Move the contents of
/home/node/.n8n/binaryData into /home/node/.n8n/storage, remove
/home/node/.n8n/binaryData, then start n8n again.
Exiting due to an error.

Der Container ist mit Exited (1) gestorben. Keine Weboberfläche, kein Webhook, nichts. Und: Dieser Punkt taucht im Migration Report nicht auf — weder bei den Workflow- noch bei den Instanz-Befunden.

Die Fehlermeldung ist vorbildlich, sie sagt dir genau, was zu tun ist. Nur liest du sie erst, wenn die Instanz schon unten ist. Prüf es vorher:

docker exec <container> ls -la /home/node/.n8n | grep -E 'binaryData|storage'
docker inspect <container> --format '{{json .Mounts}}' | jq

Liegt dort nur storage, bist du fein raus — aktuelle 2er-Versionen legen das Verzeichnis bereits unter dem neuen Namen an.

2. Der Report ist nur so gut wie die Version, auf der er läuft

Das ist der Befund, der mich am meisten überrascht hat. Ich habe dieselbe Datenbank mit denselben elf Workflows gegen drei Versionen laufen lassen:

Gleiche Daten, unterschiedliches Ergebnis. Der Unterschied ist die Regel edit-image-version-v3: Workflows mit einem Edit Image-Node in Version 1 oder 1.1 scheitern unter 3.0. Auf 2.44.7 — der aktuell als stable ausgelieferten Version — wird dieser Befund nicht angezeigt. Er existiert, mein Testworkflow enthält den Node, aber die Regel ist in dieser Version noch nicht enthalten.

Besonders unangenehm: Ausgerechnet bei diesem Punkt schickt dich die Dokumentation ausdrücklich zum Migration Report („go to Settings > Migration Report to identify affected workflows"). Wer dem auf 2.44.7 folgt, bekommt eine leere Antwort und hält seine Instanz für sauber.

Konsequenz für dich: Aktualisiere erst innerhalb der 2er-Linie auf den neuesten Stand, und lies den Report danach noch einmal. Ein Report von vor drei Wochen ist kein Report.

3. AI Transform wird beim Upgrade nicht automatisch migriert

Die Dokumentation sagt zum AI-Transform-Node, n8n migriere bestehende Nodes beim Upgrade automatisch zu Code-Nodes, unter Beibehaltung des erzeugten JavaScripts — „so existing workflows keep working without changes".

Nach meinem Upgrade von 2.44.7 auf 3.0.0 sah der Workflow so aus:

Ein Fragezeichen. Der Node liegt in der Datenbank unverändert als n8n-nodes-base.aiTransform in Version 1, das JavaScript ist noch da — aber 3.0 kennt den Typ nicht mehr und zeigt einen Platzhalter. Der Migration Report auf der 3.0-Instanz führt den Befund weiterhin als offen.

Die Migration gibt es, aber sie passiert nicht beim Upgrade: Der Report bietet sie als Aktion an, die du vorher auslösen musst. „Automatically on upgrade" beschreibt das nicht zutreffend. Wenn du AI-Transform-Nodes im Bestand hast, migriere sie aus dem Report heraus, bevor du das Image tauschst.

4. Die npm-Installation hat keinen Upgrade-Pfad

n8n 3.0 unterstützt self-hosted nur noch Docker. Es gibt kein npm-Paket mehr, das du starten könntest:

Self-hosted n8n requires a Docker-based deployment. n8n 3.0 no longer supports installations run using npm or npx n8n.

Das ist der einzige der fünf Punkte, bei dem der Report dir strukturell nicht helfen kann — er läuft innerhalb deiner Instanz und weiß nichts darüber, wie sie gestartet wurde. Läuft dein n8n als npm install -g n8n hinter einem systemd-Unit auf einer VM, ist 3.0 für dich kein Update, sondern ein Umzug. Der Report wird dir trotzdem grüne Häkchen zeigen.

Für einen Neustart auf der grünen Wiese gibt es ein Ein-Zeilen-Setup:

curl -fsSL https://get.n8n.io | sh

Für eine bestehende Produktionsinstanz ist der Weg weiter unten beschrieben — und er führt nicht über dieses Skript.

5. Beim Timeout sagt dir der Report das Was, nicht das Wer

Der Default von N8N_RUNNERS_TASK_TIMEOUT sinkt von 300 auf 60 Sekunden. Code-Nodes, die länger laufen, werden abgebrochen. Dieser Punkt steht im Report — als Instanz-Befund, korrekt und prominent.

Was er dir nicht sagt: welcher deiner Code-Nodes davon stirbt.

Ich habe einen Workflow mit einem Code-Node gebaut, der 90 Sekunden braucht, und ihn auf beiden Versionen mit identischen Daten ausgeführt:

• n8n 2.44.7: status=success nach 94 Sekunden
• n8n 3.0.0: status=error nach 61 Sekunden

TaskRunnerExecutionTimeoutError, exakt an der Minutengrenze. Der Punkt ist das Timing des Schadens: Das Upgrade läuft durch, die Oberfläche startet, alles sieht gut aus. Der Fehler kommt erst beim nächsten Lauf dieses einen Workflows — nachts, wenn der Export läuft.

Das Gegenmittel steckt in deiner eigenen Historie. Die Ausführungszeiten vergangener Läufe stehen in den Executions. Filter auf Laufzeiten über 60 Sekunden, und du hast die Liste der Workflows, die du vor dem Upgrade anfassen musst. Wenn du die Zeit nicht hast: Setz N8N_RUNNERS_TASK_TIMEOUT=300 explizit und verschieb die Entscheidung — bewusst, nicht aus Versehen.

Die Reihenfolge: parallel aufsetzen, nicht upgraden

Der naheliegende Weg wäre: Backup ziehen, auf 3.0 aktualisieren, Fehler beheben. Bei einer npm-Installation geht das nicht, weil es kein Update gibt, auf das man aktualisieren könnte. Und auch bei Docker-Setups ist es der riskantere Weg. Besser ist es, parallel aufzusetzen:

1. Report lesen — auf einer aktuellen 2er-Version, nicht auf der, die seit Monaten läuft. Dann die fünf Punkte oben prüfen, die er nicht abdeckt.
2. Zweite Instanz aufsetzen, in Docker, auf demselben Server oder einer frischen VM. Noch nicht öffentlich erreichbar.
3. Datenbank-Dump ziehen und einspielen. Bei SQLite die Datei, bei Postgres pg_dump. Den N8N_ENCRYPTION_KEY mitnehmen, sonst sind alle Credentials unlesbar — das gilt auch für den Testlauf.
4. Nodes ersetzen und Migrationen aus dem Report auslösen, Workflow für Workflow.
5. Testen, vor allem die Zeitsteuerung (siehe unten).
6. Umschalten: alte Instanz stoppen, Reverse Proxy und DNS auf die neue zeigen lassen, Webhooks prüfen.
7. Alte Instanz eine Weile stehen lassen, gestoppt, aber nicht gelöscht.

Bis Schritt 6 läuft deine Produktion unverändert weiter. Geht etwas schief, ist der Rückweg ein Neustart der alten Instanz.

Weil 3.0.0 als Image bereits verfügbar ist, kannst du die Schritte 2 bis 5 heute durchspielen — auf einer Kopie, ohne Risiko. Genau so sind die Messungen in diesem Artikel entstanden.

Cron und Interval: Warum das Ersetzen mehr ist als ein Klick

Cron und Interval werden durch den Schedule Trigger ersetzt. Das klingt nach Suchen und Ersetzen, ist es aber nicht. Der Schedule Trigger verhält sich beim Nachholen verpasster Ausführungen anders.

Wer nächtliche Jobs hat, muss das wissen. Ein Beispiel: Die Instanz ist um 2 Uhr wegen eines Server-Neustarts nicht erreichbar, und um 2 Uhr hätte der Export laufen sollen. Ob er beim nächsten Start nachgeholt wird oder bis zur nächsten Nacht ausfällt, entscheidet darüber, ob morgens Daten fehlen.

Verlass dich hier nicht auf die Erwartung, sondern teste es auf der zweiten Instanz: Zeitplan auf die nächsten Minuten setzen, Instanz vor dem Zeitpunkt stoppen, danach starten und in den Executions nachsehen, was passiert ist.

Seit 2.45 ist das keine reine Glaubensfrage mehr, sondern eine Einstellung am Node — und dieselbe Umstellung verschiebt nebenbei die Uhrzeiten deiner Minuten-Intervalle. Beides steht in n8n 2.45: Dein Minuten-Zeitplan läuft ab jetzt woanders los.

Kurz für Agenturen: der Entwickler-Laptop

Wer eigene Nodes baut, ist an einer anderen Stelle betroffen, die in keinem Workflow steckt und die der Report nicht sieht:

• n8n-node dev braucht Docker oder Podman. Der Befehl startete n8n bisher über npx n8n@latest. Weil es dieses Paket nicht mehr gibt, läuft er jetzt gegen das offizielle Image im Container. build, lint, release und npm create @n8n/node bleiben unverändert.
• Testdaten wandern in Container-Volumes. Workflows und Credentials aus dem Test-Loop liegen nicht mehr unter ~/.n8n-node-cli/.n8n, sondern in einem Volume pro Image. Beim Wechsel des Images sind sie weg — exportiere, was du behalten willst.
• defaults.color ist entfernt. Nodes mit Font-Awesome-Icon werden neutral eingefärbt statt bunt. Nichts bricht, aber dein Node sieht anders aus. Ersetze das Icon durch eine SVG- oder PNG-Datei.

Fazit

Der Migration Report nimmt dir echte Arbeit ab — mehr, als seine eigene Dokumentation verspricht. Die selbstgebaute Inventur über CLI und jq brauchst du für entfernte Nodes und für die großen Konfigurations-Defaults nicht mehr.

Verlass dich trotzdem nicht allein auf ihn:

• Erst die 2er-Linie aktualisieren, dann den Report lesen. Auf 2.44.7 fehlt mindestens eine Regel, die 2.46.0 und 3.0.0 kennen. Der Report ist nur so vollständig wie die Version, in der er läuft.
• binaryData neben storage ist der einzige Punkt, der die Instanz gar nicht mehr starten lässt — und er steht nicht im Report. Ein ls kostet dich zehn Sekunden.
• AI-Transform-Nodes vor dem Imagetausch migrieren, aus dem Report heraus. „Automatisch beim Upgrade" ist in der Praxis ein Platzhalter im Canvas.
• Beim Timeout die Executions-Historie befragen, nicht den Report. Er kennt die Einstellung, nicht deine Laufzeiten.
• Eine npm-Installation sieht im Report sauber aus und hat trotzdem keinen Weg nach 3.0.

Alle Zahlen in diesem Artikel stammen aus einem Durchlauf am 27.10.2026 mit n8n 2.44.7, 2.46.0 und 3.0.0. Da 3.0.0 noch als Release Candidate ausgeliefert wird und die Breaking-Changes-Seite sich nachweislich mehrmals pro Woche ändert, prüf die Punkte am Tag deiner Migration noch einmal gegen die dann aktuelle Dokumentation.

Du betreibst n8n auf einem eigenen Server und willst den Umzug nicht nebenbei machen? Sprich mich an. Die Inventur ist meistens in einem Termin erledigt, und danach weißt du, wie groß die Migration wirklich ist.