n8n 1 auf 2 migrieren: Breaking Changes & Checkliste

Wenn Sie n8n selbst hosten, betrifft Sie das nächste große Update direkter als Cloud-Kunden: Bei einer eigenen Instanz entscheiden Sie, wann Sie aktualisieren – und tragen die Verantwortung dafür, dass danach alles weiterläuft. Mit n8n 2.0 hat der Anbieter einen Versionssprung veröffentlicht, der ausdrücklich als Major Release gekennzeichnet ist. Und ein Major Release bedeutet bei n8n per Definition genau das, was IT-Verantwortliche fürchten: Änderungen, die manuelles Eingreifen erfordern.

n8n nutzt nach eigener Angabe (öffnet in neuem Tab) Semantic Versioning (öffnet in neuem Tab). Die Regel dazu steht klar in der Dokumentation: Die MAJOR-Version steigt „when making incompatible changes which can require user action" – also bei nicht abwärtskompatiblen Änderungen, die ein Eingreifen erfordern können. Genau deshalb ist der Sprung von 1.x auf 2.0 kein Update, das Sie unbesehen durchlaufen lassen sollten.

Dieser Beitrag fasst zusammen, welche Breaking Changes n8n selbst dokumentiert, welche davon typische Mittelstands-Setups treffen und wie Sie das Upgrade strukturiert vorbereiten. Alle genannten Änderungen stammen aus der offiziellen Breaking-Changes-Seite von n8n (öffnet in neuem Tab) – nicht aus Erfahrungsberichten Dritter.

Wann kam n8n 2.0 – und was ist der Kern der Umstellung?

Laut den Release Notes von n8n (öffnet in neuem Tab) wurde n8n 2.0 am 8. Dezember 2025 veröffentlicht. Der Anbieter beschreibt den Charakter des Releases dort selbst: Es gehe um „important security enhancements and cleanup of deprecated features" – also um Sicherheitsverbesserungen und das Aufräumen veralteter Funktionen, nicht primär um neue Features.

Diese Ausrichtung erklärt, warum die meisten Breaking Changes in eine von zwei Kategorien fallen: Entweder wird eine Standardeinstellung strenger (Sicherheit), oder eine alte Möglichkeit fällt weg (Aufräumen). Beides kann bestehende Workflows stören, wenn Sie sich bisher auf das lockerere Verhalten verlassen haben.

Der Migration Report: Erst prüfen, dann upgraden

Bevor wir in die einzelnen Änderungen gehen, die wichtigste organisatorische Neuerung vorweg. n8n stellt ein eigenes Werkzeug bereit, das Ihre Instanz auf Kompatibilität prüft. Laut n8n-Dokumentation zum Migration Tool (öffnet in neuem Tab) erreichen Sie es über Settings > Migration Report. Die Funktion ist dort ausschließlich für „global admins" verfügbar.

Der Report zeigt oben eine Kompatibilitätsübersicht im Format „X out of Y workflows are compatible with n8n 2.0" und teilt die Probleme in zwei Registerkarten: Workflow Issues (betrifft einzelne Workflows) und Instance Issues (betrifft die gesamte Instanz-Konfiguration). Jedes Problem trägt laut Dokumentation eine Einstufung – Critical, Medium oder Low. n8n beschreibt die Stufen so:

• Critical: „Fix before upgrading or workflows will fail" – vor dem Upgrade beheben, sonst brechen Workflows.
• Medium: „May cause unexpected behavior or require attention soon" – kann zu unerwartetem Verhalten führen.
• Low: „Minor changes or deprecations that won't break functionality" – Abkündigungen, die noch nichts kaputtmachen.

Für die Praxis heißt das: Der Migration Report ist Ihr Ausgangspunkt, nicht dieser Artikel. Er sagt Ihnen konkret, welche der folgenden Änderungen Ihre Instanz überhaupt betreffen und wie viele Workflows jeweils betroffen sind. Alles Weitere in diesem Beitrag hilft Ihnen, die Meldungen des Reports einzuordnen.

Die Datenbank-Frage: MySQL und MariaDB fallen weg

Die folgenschwerste Änderung für viele bestehende Installationen betrifft das Speicher-Backend. n8n dokumentiert: „n8n will no longer support MySQL and MariaDB as storage backends." Der Support dafür war laut n8n bereits in Version 1.0 als veraltet gekennzeichnet worden.

Wichtig ist hier eine feine, aber entscheidende Unterscheidung, die n8n ausdrücklich macht: Es geht um MySQL/MariaDB als Speicher- Backend der n8n-Instanz selbst. Der MySQL-Node – mit dem Sie in Workflows auf eine MySQL-Datenbank zugreifen – bleibt erhalten. In der Doku steht dazu wörtlich: „MySQL node will continue to be supported as before."

Als Migrationspfad nennt n8n: Vor dem Upgrade die Daten mit dem Datenbank-Migrationswerkzeug von MySQL oder MariaDB nach PostgreSQL oder SQLite überführen. Für langfristige Kompatibilität empfiehlt n8n PostgreSQL.

SQLite wird schneller – aber der Legacy-Treiber verschwindet

Wer SQLite nutzt, ist ebenfalls betroffen. n8n entfernt den bisherigen SQLite-Legacy-Treiber „due to reliability issues". Standard wird der Pooling-Treiber, der laut n8n mit WAL-Modus, einer einzelnen Schreibverbindung und einem Pool von Leseverbindungen arbeitet. Zur Geschwindigkeit macht n8n eine konkrete Angabe: „Our benchmarks show it can be up to 10 times faster." Diese Zahl stammt aus n8ns eigenen Benchmarks und ist entsprechend als Anbieterangabe zu lesen.

Die gute Nachricht: Der Wechsel geschieht laut Doku automatisch – „the sqlite-pooled driver will become the default automatically". Die voreingestellte Pool-Größe wird auf 2 gesetzt. Testen können Sie das Verhalten schon vorher, indem Sie DB_SQLITE_POOL_SIZE auf einen Wert größer 0 setzen.

Sicherheit: Der Code-Node wird strenger

Ein Bündel von Änderungen macht den Code-Node sicherer – und potenziell inkompatibel mit bestehenden Skripten.

Task Runner sind jetzt Standard. n8n aktiviert Task Runner (öffnet in neuem Tab) standardmäßig, „to improve security and isolation". Alle Code-Node-Ausführungen laufen künftig auf Task Runnern. n8n empfiehlt, das vor dem Upgrade mit N8N_RUNNERS_ENABLED=true zu testen und sicherzustellen, dass die Infrastruktur die Anforderungen erfüllt.

Umgebungsvariablen sind im Code-Node blockiert. Der Standardwert von N8N_BLOCK_ENV_ACCESS_IN_NODE ist jetzt true. Wenn Ihre Workflows im Code-Node auf Umgebungsvariablen zugreifen, müssen Sie das explizit über N8N_BLOCK_ENV_ACCESS_IN_NODE=false erlauben. n8n empfiehlt allerdings, für sensible Daten stattdessen Credentials zu nutzen.

$evaluateExpression() funktioniert nicht mehr im Code-Node. Weil Code-Node-Ausführungen jetzt im Secure Mode auf Task Runnern laufen, ist diese Komfortmethode dort deaktiviert. n8n schreibt, entsprechende Aufrufe geben „null or error" zurück. Ausdrücke in regulären Node-Feldern wie dem Edit-Fields-(Set)-Node sind davon nicht betroffen. Als Migrationspfad empfiehlt n8n, die Logik direkt in JavaScript zu schreiben oder den Ausdruck vorab in einem Set-Node auszuwerten. Der Notausgang N8N_RUNNERS_INSECURE_MODE=true schaltet die Sicherheitsmaßnahmen wieder ab – n8n bezeichnet ihn ausdrücklich als „temporary workaround rather than a permanent solution".

Python im Code-Node ändert sich grundlegend. n8n entfernt den Pyodide-basierten Python-Code-Node und ersetzt ihn durch eine Task-Runner-basierte Variante mit nativem Python. Ab n8n 2.0 lassen sich Python-Code-Nodes laut Doku „only … with task runners in external mode" nutzen. Der native Python-Node unterstützt außerdem die bisherigen Built-in-Variablen wie _input und die Punkt-Zugriffs-Notation nicht mehr. Wer Python in n8n einsetzt, sollte diesen Punkt besonders sorgfältig prüfen.

Weitere Sicherheits-Standards, die Sie treffen können

n8n zieht mehrere weitere Voreinstellungen an:

• ExecuteCommand und LocalFileTrigger sind standardmäßig deaktiviert, weil sie beliebige Befehle ausführen bzw. auf das Dateisystem zugreifen können. Wer sie braucht, muss sie über NODES_EXCLUDE wieder freischalten.
• OAuth-Callback-URLs verlangen jetzt Authentifizierung. Der Standard von N8N_SKIP_AUTH_ON_OAUTH_CALLBACK wechselt von true auf false. n8n rät, das vorab zu setzen und die OAuth-Integrationen zu testen.
• Der Dateizugriff ist eingeschränkt. Über N8N_RESTRICT_FILE_ACCESS_TO bekommt der Zugriff der Datei-Nodes (ReadWriteFile, ReadBinaryFiles) einen Standardwert. Standardmäßig dürfen diese Nodes nur noch auf das Verzeichnis ~/.n8n-files zugreifen.
• Konfigurationsdateien brauchen strenge Rechte. Standardmäßig verlangt n8n 0600-Berechtigungen – vergleichbar damit, wie SSH private Schlüssel schützt. Auf Windows, wo Dateirechte nicht greifen, lässt sich das per N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=false abschalten.
• Der Git-Node blockiert Bare-Repositories. N8N_GIT_NODE_DISABLE_BARE_REPOS steht jetzt auf true.

Diese Punkte sind einzeln harmlos, in Summe aber der häufigste Grund, warum ein Workflow nach dem Upgrade „plötzlich" nicht mehr läuft. Der Migration Report unter Instance Issues zeigt Ihnen, welche davon Ihre Konfiguration betreffen.

Aufgeräumt: Was ganz verschwindet

Neben verschärften Standards entfernt n8n eine Reihe von Altlasten komplett.

Der Start-Node ist weg. Er war laut n8n „the original way to begin workflows", wird nun aber durch spezifischere Trigger-Nodes ersetzt. Der Migrationspfad hängt vom Einsatzzweck ab: Für manuelle Ausführungen ersetzen Sie ihn durch einen Manual Trigger, bei Sub-Workflows durch einen Execute Workflow Trigger (und aktivieren den Workflow), deaktivierte Start-Nodes löschen Sie einfach.

Vier Nodes für eingestellte Dienste fallen weg – Spontit, crowd.dev, Kitemaker und Automizy –, weil die dahinterstehenden Dienste laut n8n nicht mehr verfügbar sind. Workflows, die diese Nodes nutzen, müssen angepasst oder entfernt werden.

Weitere Abkündigungen und Entfernungen laut Doku:

• Die CLI-Option n8n --tunnel wird entfernt. n8n verweist auf Alternativen wie ngrok, localtunnel oder Cloudflare Tunnel.
• Die Umgebungsvariable N8N_CONFIG_FILES wird entfernt; Konfiguration soll über Env-Variablen, eine .env-Datei oder _FILE-basierte Konfiguration erfolgen.
• Die dotenv-Bibliothek wird von Version 8.6.0 auf die neueste Version angehoben, was das Parsen von .env-Dateien ändern kann – etwa beim Umgang mit Backticks und Kommentaren.
• Der In-Memory-Modus für Binärdaten (N8N_DEFAULT_BINARY_DATA_MODE=default) wird entfernt.

Verhalten ändert sich: Publish statt Activate – und Sub-Workflows

Zwei Änderungen betreffen weniger die Konfiguration als die tägliche Arbeit.

Aus „Activate/Deactivate" wird „Publish/Unpublish". n8n ersetzt den alten Aktiv/Inaktiv-Umschalter durch ein Publishing-System. Der Nutzen laut n8n: bessere Kontrolle darüber, wann Änderungen live gehen – „reducing the risk of accidentally deploying work-in-progress changes to production". Wer bisher Änderungen speicherte und dabei versehentlich Halbfertiges in Produktion schob, bekommt hier eine echte Trennung von Speichern und Veröffentlichen.

Ergänzt wird das durch Autosave. Laut der Ankündigung im n8n-Community-Forum (öffnet in neuem Tab) ist Autosave „always on" und prüft beim Bearbeiten alle 2 Sekunden auf Änderungen, um sie automatisch zu speichern. Beide Funktionen greifen ineinander: Ihre Bearbeitungen werden fortlaufend gesichert, gehen aber erst mit dem bewussten Veröffentlichen in Produktion.

Sub-Workflows geben andere Daten zurück. Diese Änderung ist subtil und deshalb gefährlich. Bisher erhielt ein Eltern-Workflow, der einen Sub-Workflow aufrief, der in einen Wartezustand ging (etwa durch einen Wait-Node über 65 Sekunden, einen Webhook, eine Formular-Übermittlung oder einen Human-in-the-Loop-Node), laut n8n „incorrect results" – konkret die Eingabe des Sub-Workflows statt dessen Ergebnis. In n8n 2.0 erhält der Eltern-Workflow nun das tatsächliche Ergebnis am Ende des Kind-Workflows. n8n weist ausdrücklich darauf hin, alle Workflows zu prüfen, die Sub-Workflows aufrufen und deren Eingabe zurückerwarten.

Praktische Checkliste vor dem Upgrade

Aus den dokumentierten Änderungen ergibt sich ein pragmatisches Vorgehen. n8n selbst empfiehlt im Migration Tool (öffnet in neuem Tab) diese Reihenfolge:

1. Migration Report öffnen (Settings > Migration Report, nur als Global Admin) und die Kompatibilitätsübersicht lesen.
2. Nach Schweregrad sortieren: zuerst Critical, dann Medium, zuletzt Low.
3. Workflow-Probleme beheben: betroffene Workflows anklicken, die verlinkte Dokumentation lesen, anpassen und in einer Entwicklungs- bzw. Staging-Umgebung testen.
4. Instance-Probleme adressieren: Umgebungsvariablen und Server-Konfiguration nach den Doku-Hinweisen anpassen.
5. Neu prüfen: über Refresh erneut scannen und kontrollieren, dass keine offenen Punkte bleiben.
6. Erst dann upgraden.

Zwei ergänzende Empfehlungen aus der Doku sind es wert, betont zu werden. Erstens: n8n empfiehlt, die eigene Version fest zu pinnen – „Pin your n8n version to a specific version number, for example, 2.0.0." Zweitens hat n8n die Release-Kanäle umbenannt: aus latest und next werden stable und beta. Die alten Tags bleiben laut Doku vorerst erhalten, sollen aber in einer künftigen Major-Version entfernt werden. Wer in Docker-Setups blind auf latest zieht, sollte das im Hinterkopf behalten.

Fazit: Ein Wartungsfenster, kein Klick

n8n 2.0 ist kein Feature-Feuerwerk, sondern ein Aufräum- und Sicherheits-Release – und genau deshalb verdient es Aufmerksamkeit. Die riskantesten Änderungen sind die leisen: ein Sub-Workflow, der plötzlich andere Daten liefert, ein Code-Node ohne Zugriff auf eine Umgebungsvariable, ein Python-Skript, das die alte Notation nutzt. Solche Fehler brechen nicht laut, sondern liefern falsche Ergebnisse – und das fällt im schlimmsten Fall erst auf, wenn eine Rechnung, eine Lead-Weiterleitung oder ein Report bereits schiefgelaufen ist.

Die gute Nachricht: n8n liefert mit dem Migration Report ein Werkzeug, das Ihnen die Prüfarbeit strukturiert. Behandeln Sie das Upgrade als geplantes Wartungsfenster mit Staging-Test statt als schnellen Klick, und die meisten Stolpersteine sind vorher sichtbar. Wenn Sie Ihre Automatisierungen produktiv betreiben und beim Upgrade oder bei der Bewertung Ihrer Workflows Unterstützung brauchen, begleiten wir Sie gern bei der Migration – von der Bestandsaufnahme bis zum verifizierten Go-live.