Seit dem 27. Oktober gibt es die Beta von n8n 3.0. Die stabile Version soll Anfang Dezember folgen. Der Major-Sprung ist kein Marketing: n8n räumt Legacy-Nodes ab, verschärft Security-Defaults und baut Teile der Ausführung um. Manuelle Executions laufen im Queue Mode künftig immer auf Workern, der In-Memory-Modus für Binärdaten fällt weg und das Timeout für den Code-Node sinkt von fünf Minuten auf eine.
Meine n8n-Instanz ist inzwischen ein zentraler Baustein in meinem Homelab. Sie läuft self-hosted mit Docker, PostgreSQL, Redis im Queue Mode und externen Task Runnern. Dazu kommen 216 Workflows, von denen einige täglich oder auch mehrfach am Tag laufen. Ich wollte deshalb nicht direkt auf die Beta springen, sondern die Instanz noch auf 2.x so vorbereiten, dass der eigentliche Upgrade-Schritt unspektakulär wird.
Ein Punkt hat mich dabei besonders vorsichtig gemacht: Der Weg auf 3.x ist eine Einbahnstraße. Zurück auf 2.x geht es nur über ein Backup.
Der Migration Report als Ausgangspunkt
Seit Version 2.39 bringt n8n unter Settings → Migration report ein Werkzeug mit, das genau für diese Vorbereitung gedacht ist. Der Report prüft zwei Dinge:
- Workflow issues: Alle Workflows werden auf Nodes untersucht, die in v3 wegfallen oder sich anders verhalten.
- Instance issues: Die Konfiguration der Instanz selbst, also Umgebungsvariablen und Defaults, die sich ändern.
Jeder Punkt ist mit einem Label versehen. „Executions will fail" heißt: Nach dem Upgrade bricht etwas. „Behavior changes" heißt: Es läuft weiter, liefert aber womöglich ein anderes Ergebnis. Diese Unterscheidung hilft beim Priorisieren enorm.
Bei mir sah der Ausgangszustand so aus: 212 von 216 Workflows kompatibel, drei Workflow-Themen und sieben Instance-Themen.
Der Reiter für die Instanz zeigt die Infrastruktur-Themen. Hier wird es für Self-Hoster interessant, denn diese Punkte lassen sich nicht im Editor lösen, sondern nur im Docker-Setup.
Die für mich relevanten Instance-Themen im Überblick:
| Thema | Variable | Alt | Neu in v3 |
|---|---|---|---|
| Compression-Limits | N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES / N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES |
2 GiB / 5000 | 256 MiB / 1000 |
| Task-Runner-Timeout | N8N_RUNNERS_TASK_TIMEOUT |
300 s | 60 s |
| Manuelle Executions | OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS |
optional | entfällt, immer auf Workern |
| Storage-Verzeichnis | N8N_MIGRATE_FS_STORAGE_PATH |
~/.n8n/binaryData |
~/.n8n/storage |
| Unverified Community Packages | N8N_UNVERIFIED_PACKAGES_ENABLED |
true |
false |
| Binary-Data-Modus | N8N_DEFAULT_BINARY_DATA_MODE |
default (In-Memory) |
default ist nicht mehr gültig |
Die vollständige Liste steht in der Dokumentation zu den Breaking Changes.
Erst der Snapshot, dann alles andere
n8n läuft bei mir in einem LXC-Container auf Proxmox. Bevor irgendjemand, Mensch oder Agent, an der Konfiguration dreht, gibt es einen Snapshot. Das kostet ein paar Sekunden und ist im Zweifel der schnellste Weg zurück.
Instanz-Check mit OpenCode
Mein Docker-Setup für n8n liegt als Repository lokal auf meinem Rechner, der Agent hat zusätzlich SSH-Zugriff auf den Server. Für die Prüfung habe ich OpenCode in einer Session in herdr gestartet. Im Screenshot ist noch GPT-6.1 Terra ausgewählt, die eigentliche Arbeit hat dann aber GPT-6.1 Sol von OpenAI erledigt.
Der Prompt war bewusst kurz. Dazu kam der Inhalt der Instance Issues aus dem Migration Report per Copy & Paste. Der Agent hat keinen Zugriff auf die UI des Reports, also habe ich ihm die relevanten Informationen direkt mitgegeben.
Erst analysieren, nichts ändern
Positiv aufgefallen ist mir, dass der Agent im ersten Durchlauf nur analysiert hat. Keine Datei geändert, nichts neu gestartet. Stattdessen gab es eine Bestandsaufnahme:
Der wichtigste Fund war für mich der Deployment-Drift. Die docker-compose.yml auf dem Server enthielt Änderungen, die nie ins Repository zurückgeflossen sind, unter anderem eine AI-Sandbox und SearXNG. Hätte der Agent einfach die lokale Datei hochkopiert, wären diese Dienste weg gewesen. Er hat das erkannt und die Server-Änderungen als „muss erhalten bleiben" markiert. Ehrlicherweise ist das ein Problem, das ich selbst verursacht habe.
Auch beim Task-Runner-Timeout fand ich die Argumentation nachvollziehbar: In einer Stichprobe von 259 Executions gab es sieben Code-Node-Läufe, alle unter 1,5 Sekunden. Das spricht eigentlich für den neuen Default von 60 Sekunden. Eine Stichprobe sagt aber nichts über den Worst Case aus. Deshalb lautete die Empfehlung, die 300 Sekunden vorerst explizit zu setzen. Das ist konservativ, aber für mich der richtige erste Schritt.
Zusätzlich hat der Agent zwei aktive Workflows gefunden, die Nodes verwenden, die in v3 entfernt werden:
Er weist dabei selbst darauf hin, dass das nur eine gezielte Prüfung ist und kein Ersatz für den Migration Report. Daraus entstand ein Vorschlag für einen „v2 preparation pass": Die Instanz bleibt auf 2.x, wird aber so konfiguriert, dass sie sich schon wie v3 verhält oder die alten Werte explizit beibehält.
Die Vorbereitung auf 2.44.6
Nach meiner Freigabe hat der Agent folgende Änderungen umgesetzt und geprüft:
- Versionen gepinnt inklusive Image-Digests für n8n und die Task Runner. Damit kann mir kein
latest-Tag versehentlich die Beta unterschieben. N8N_RUNNERS_TASK_TIMEOUT=300auf Main, Worker und beiden Runnern.N8N_UNVERIFIED_PACKAGES_ENABLED=true, damit meine Community-Nodes weiter laden.- Binary Storage explizit auf
database, da der implizite Default wegfällt. - Offloading manueller Executions auch auf Main, sodass ich das künftige Verhalten schon unter v2 testen kann.
Beim Thema Unverified Packages bin ich nicht ganz glücklich. n8n schaltet das in v3 aus gutem Grund ab. Ich habe es erst einmal aktiviert gelassen, damit nichts bricht. Mittelfristig will ich prüfen, welche Community-Nodes ich wirklich brauche und ob es dafür verifizierte Alternativen gibt.
Zweite Runde: Compression und Storage-Verzeichnis
Danach blieben noch zwei Themen offen, für die es eine kurze zweite Runde gab:
Da in keinem meiner Workflows ein Compression-Node vorkommt, gab es keinen Grund, die alten, großzügigen Limits zu behalten. Die neuen Werte explizit zu setzen entfernt außerdem die Warnung aus dem Report.
Für das Storage-Verzeichnis gibt es mit N8N_MIGRATE_FS_STORAGE_PATH=true einen Schalter, der die Umbenennung von binaryData nach storage schon unter 2.x durchführt. Da bei mir das komplette .n8n-Verzeichnis als Volume eingebunden ist, war keine Anpassung am Mount nötig. Der Agent hat Main und Worker gestoppt, damit nicht beide parallel migrieren, und sie anschließend nacheinander gestartet. Beim Upgrade auf v3 kann der Schalter wieder raus.
Workflows von Hand umstellen
Die betroffenen Workflows habe ich manuell angepasst. Das wäre sicher auch über den Instance-level MCP-Server von n8n mit einem Agenten gegangen. Bei einer Handvoll Nodes war ich so aber schneller und konnte das Ergebnis direkt im Editor prüfen.
Der Migration Report gibt die Richtung vor:
- Convert to/from Binary Data, Richtung JSON/Base64 → Datei: ersetzen durch Convert to File.
- Convert to/from Binary Data, Richtung Datei → Base64: ersetzen durch Extract From File mit „Move File to Base64 String".
- Write Binary File: ersetzen durch Read/Write Files from Disk mit „Write File to Disk".
In meinem Workflow für die Adobe-Commerce-Versionsinformationen wird eine JSON-Struktur als Datei per SSH auf einen Server hochgeladen. Aus dem alten Move Binary Data (JSON to Binary) wurde ein Convert to File:
Die Einstellungen sind überschaubar: Operation „Convert to JSON", Mode „Each Item to Separate File" und das Ausgabefeld data, damit der nachfolgende SSH-Node das Binärfeld wie bisher findet. Wichtig ist, danach einmal auszuführen und den Output zu vergleichen. Hier landet wie zuvor das JSON mit den Versionen in der Datei.
Always Output Data: die stille Verhaltensänderung
Der dritte Punkt im Report ist der tückischste, weil er nichts kaputt macht, sondern nur anders routet. Bei Nodes mit mehreren Ausgängen, etwa If oder Switch, hängt „Always Output Data" bisher ein leeres Item an den ersten Ausgang, auch wenn ein anderer Ausgang Daten geliefert hat. In v3 wird das leere Item nur noch erzeugt, wenn alle Ausgänge leer sind.
Praktisch finde ich, dass der Report Workflows erkennt, die seit über zwölf Monaten nicht gelaufen sind, und anbietet, sie gesammelt als „Won't fix" zu markieren. Das hält die Liste sauber, ohne dass man sich durch Altlasten arbeiten muss.
Bei mir war die Sache schnell erledigt. Ich habe mir beide Workflows angeschaut. An den betroffenen Stellen wird immer nur ein Item verarbeitet, die geänderte Logik wirkt sich also nicht aus. Beide Workflows habe ich deshalb im Migration Report auf „Won't fix" gesetzt. Das bedeutet nicht, dass man das Thema ignoriert. Man dokumentiert, dass man es geprüft und bewusst entschieden hat. Wenn ein Workflow mehrere Items über If- oder Switch-Nodes verteilt, lohnt sich ein genauerer Blick auf die Ausgaben.
Das Ergebnis
Nach den Anpassungen meldet der Migration Report 216 von 216 kompatiblen Workflows und keine Workflow-Issues mehr.
Zwei Instance Issues bleiben offen. Beide tragen das Label „Capability removed" und sind eher Hinweise als To-dos:
- Chat Hub ist deprecated und standardmäßig aus. In v3 verschwindet der Bereich „Chat" aus der Oberfläche. Er lässt sich über
N8N_ENABLED_MODULESwieder aktivieren, mit v4 wird das Feature aber komplett entfernt. - „Import from URL" im Editor entfällt.
Ich nutze beides nicht, daher gibt es hier nichts zu tun. Wer den Chat Hub produktiv einsetzt, sollte sich aber jetzt schon Gedanken über eine Alternative machen. Das Wiedereinschalten verschiebt das Problem nur bis v4.
Die Instanz läuft weiterhin stabil auf 2.44.6. Der eigentliche Wechsel auf v3 ist jetzt im Wesentlichen ein Tausch des Image-Tags plus das Entfernen der Übergangsvariablen.
Meine Einschätzung
Der Migration Report ist das beste Upgrade-Werkzeug, das ich bisher in n8n gesehen habe. Statt ein Changelog gegen 216 Workflows abzugleichen, bekomme ich eine konkrete Liste mit Handlungsempfehlungen. Die Einordnung in „bricht" und „verhält sich anders" spart Zeit.
Der Agent war vor allem beim Infrastruktur-Teil hilfreich: Konfiguration lesen, Executions auswerten, Drift erkennen, Änderungen umsetzen und verifizieren. Das sind Aufgaben, die ich selbst hätte erledigen können, die aber deutlich länger gedauert hätten. Dass er vor jeder Änderung und jedem Neustart nach Freigabe gefragt hat, war für mich Voraussetzung.
Es gibt aber auch Grenzen:
- Der Agent sieht den Migration Report nicht. Ich musste den Inhalt selbst übergeben.
- Die Empfehlungen muss ich bewerten können. Ob 300 Sekunden Timeout sinnvoll sind oder Unverified Packages aktiv bleiben dürfen, ist eine Entscheidung, die ich treffe, nicht das Modell.
- Ohne Snapshot und gepinnte Versionen würde ich so etwas nicht laufen lassen.
Fazit
Wer n8n selbst betreibt, sollte sich den Migration Report jetzt anschauen, nicht erst wenn die stabile 3.0 erscheint. Mein Vorgehen in Kurzform:
- Auf die aktuelle 2.x aktualisieren und den Migration Report öffnen.
- Snapshot oder Backup anlegen.
- Instance Issues im Docker-Setup lösen, möglichst schon unter 2.x.
- Betroffene Workflows umstellen und die Ausgaben vergleichen.
- Geprüfte, nicht betroffene Punkte und Altlasten als „Won't fix" markieren.
- Erst dann auf v3 wechseln, idealerweise zuerst auf einer Testinstanz.
Mit der vorbereiteten Instanz sehe ich dem Upgrade auf v3 relativ entspannt entgegen (ähnlich wie bei meiner Migration zu v2 vor einem Jahr).