Große Binärdaten: warum 100 PDFs den Server killen

Wenn ein Workflow plötzlich 100 PDFs auf einmal verarbeiten soll, sieht das auf dem Papier nach einer einfachen Aufgabe aus: Dateien einlesen, Text extrahieren, weiterreichen. In der Praxis crasht genau dieser Workflow oft mitten in der Ausführung, der n8n-Container wird neu gestartet, und im Log steht nur ein nüchternes "Out of memory". Der Grund liegt fast immer an derselben Stelle: n8n hält Binärdaten standardmäßig im Arbeitsspeicher, nicht auf der Festplatte.

Für einzelne Dateien oder kleine Bilder fällt das kaum auf. Sobald du aber Dutzende oder hunderte PDFs, Scans oder Anhänge in einem Lauf verarbeitest, addiert sich jede einzelne Datei zum RAM-Verbrauch des Prozesses, bis der Server oder Container an seine Grenze stößt. Du kannst das reproduzierbar vermeiden, ohne den Workflow selbst umzubauen, wenn du weißt, an welcher Stellschraube du drehen musst. Dieser Artikel zeigt, warum die Speicherexplosion passiert und wie du sie über den richtigen Binärdaten-Modus in den Griff bekommst.

Warum 100 PDFs den Arbeitsspeicher sprengen

n8n unterscheidet technisch zwischen dem eigentlichen Workflow-Datenfluss und den sogenannten Binärdaten, also Dateien wie PDFs, Bildern oder Excel-Anhängen, die durch einen Workflow laufen. Laut der offiziellen Dokumentation zu Binärdaten hält n8n diese Daten standardmäßig im Arbeitsspeicher, was bei kleinen Datenmengen unproblematisch ist, bei großen Dateien oder vielen Dateien gleichzeitig aber schnell zu Performance-Problemen führt. Es gibt dabei keine eingebaute Bremse: n8n begrenzt weder, wie viele Dateien ein Workflow gleichzeitig hält, noch reserviert die Software automatisch Speicher für einen Node. Ein Workflow, der 100 PDFs aus einem Postfach oder einem Ordner einliest und mit dem Extract-from-File-Node verarbeitet, kann dadurch Datei für Datei mehr Arbeitsspeicher belegen, bis der Container sein Limit erreicht und abstürzt.

Genau dieses Muster beschreibt auch ein Nutzer im n8n-Community-Forum: Bei der Migration von rund 2.000 Datensätzen mit jeweils 150 bis 200 Anhängen brach der Workflow auf einem 8-GB-VPS nach etwa 50 verarbeiteten Dateien regelmäßig ab, weil der Standardmodus alle Binärdaten im RAM hielt. Der Effekt ist bei 100 PDFs derselbe wie bei 2.000 Anhängen, nur schneller sichtbar, wenn dein Server ohnehin knapp bemessen ist.

Die Binärdaten-Modi im Überblick

n8n bietet mehrere Speichermodi für Binärdaten, gesteuert über die Umgebungsvariable `N8N_DEFAULT_BINARY_DATA_MODE`:

• memory (Standard): Alle Dateien bleiben im Arbeitsspeicher des n8n-Prozesses. Einfach, aber ohne jede Grenze nach oben.
• filesystem: n8n schreibt Binärdaten auf die Festplatte statt in den RAM. Das verhindert laut Dokumentation Abstürze bei großen Dateien, weil der Speicherbedarf pro Ausführung deutlich sinkt.
• s3: Binärdaten wandern in einen externen S3-kompatiblen Bucket statt auf die lokale Festplatte oder in den RAM.
• database: Wird verwendet, wenn Filesystem-Mode nicht zur Verfügung steht, etwa im Queue-Modus.

Wichtig für Setups mit mehreren Workern: Laut Dokumentation unterstützt n8n den Filesystem-Modus nicht im Queue-Modus, dort muss stattdessen der Datenbank-Modus genutzt werden, sofern kein gemeinsam genutzter Speicher zur Verfügung steht.

Umstieg auf Filesystem-Mode: die schnellste Lösung

Für die meisten Single-Instance-Setups reicht es, den Modus auf Filesystem umzustellen:

• Setze die Umgebungsvariable `N8N_DEFAULT_BINARY_DATA_MODE` auf `filesystem`.
• Starte die n8n-Instanz neu, damit die Variable greift.
• Stelle sicher, dass das zugrunde liegende Volume genug Plattenplatz hat, denn jetzt landen die PDFs auf der Festplatte statt im RAM.
• Plane regelmäßige Bereinigung ein, da n8n den Ordner mit Binärdaten nicht automatisch leert, sondern das über die Ausführungsdaten-Bereinigung steuert.

Der Community-Nutzer aus dem oben genannten Thread beschreibt den Effekt so, dass die Speicherkurve nach dem Wechsel dauerhaft niedrig blieb und der vorherige Ausschlag komplett verschwand. Für einen Workflow, der 100 PDFs am Stück verarbeitet, ist das in der Regel bereits die komplette Lösung, ganz ohne Codeänderung im Workflow selbst.

S3-Mode, wenn Filesystem nicht reicht

Läuft deine n8n-Instanz im Queue-Modus mit mehreren Workern auf getrennten Maschinen, hilft lokaler Festplattenspeicher nur bedingt, weil nicht jeder Worker automatisch Zugriff auf dieselben Dateien hat. Für diesen Fall beschreibt die Dokumentation zu externem Speicher die S3-Anbindung. Konfiguriert wird sie über mehrere Umgebungsvariablen:

• `N8N_EXTERNAL_STORAGE_S3_HOST`, `N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME` und `N8N_EXTERNAL_STORAGE_S3_BUCKET_REGION` für die Zielinfrastruktur.
• `N8N_EXTERNAL_STORAGE_S3_ACCESS_KEY` und `N8N_EXTERNAL_STORAGE_S3_ACCESS_SECRET` für die Zugangsdaten.
• `N8N_AVAILABLE_BINARY_DATA_MODES=filesystem,s3` und `N8N_DEFAULT_BINARY_DATA_MODE=s3`, um den Modus tatsächlich zu aktivieren.

Wichtig zu wissen: Laut Dokumentation setzt die S3-Anbindung eine gültige Enterprise-Lizenz voraus, ohne die n8n in diesem Modus nicht startet. Außerdem solltest du im Bucket eine Lifecycle-Policy einrichten, die alte Binärdaten automatisch löscht, weil n8n selbst dort nicht aufräumt.

Aufräumen nicht vergessen: Ausführungsdaten-Bereinigung

Selbst mit Filesystem- oder S3-Mode wächst dein Speicherbedarf weiter, wenn alte Ausführungen nie gelöscht werden. Die Dokumentation zur Verwaltung von Ausführungsdaten beschreibt dafür folgende Variablen:

• `EXECUTIONS_DATA_PRUNE` aktiviert die automatische Bereinigung.
• `EXECUTIONS_DATA_MAX_AGE` legt fest, nach wie vielen Stunden eine abgeschlossene Ausführung als löschbar gilt, Standardwert 336 Stunden, also 14 Tage.
• `EXECUTIONS_DATA_PRUNE_MAX_COUNT` begrenzt zusätzlich die maximale Anzahl gespeicherter Ausführungen, Standardwert 10.000.
• `EXECUTIONS_DATA_HARD_DELETE_BUFFER` sorgt für eine Karenzzeit von standardmäßig einer Stunde, bevor Daten endgültig entfernt werden.

Ein Detail, das leicht übersehen wird: Die Bereinigung wirkt laut Dokumentation immer nur auf den aktuell aktiven Binärdaten-Modus. Wechselst du also von Filesystem zu S3, bleiben eventuell alte Dateien auf der lokalen Festplatte liegen und müssen manuell entfernt werden.

Wenn du unsicher bist, welcher Modus zu deinem Setup passt, oder ein bestehender n8n-Workflow bei größeren PDF-Mengen regelmäßig abstürzt, schauen wir uns das im Rahmen unserer n8n-Automatisierung gern gemeinsam an. Als digitale Mitarbeiter richten wir die Konfiguration einmal sauber ein, dokumentieren sie und übergeben sie dir so, dass du danach die Kontrolle über deine Server-Ressourcen behältst.

Häufige Fragen

Warum crasht n8n erst ab einer bestimmten Anzahl PDFs, nicht sofort?

Weil im Standardmodus jede einzelne Datei zusätzlichen Arbeitsspeicher belegt. Bei wenigen kleinen Dateien bleibt genug Puffer übrig, mit jeder weiteren PDF im selben Lauf steigt der RAM-Verbrauch aber weiter, bis der verfügbare Speicher des Containers oder Servers erschöpft ist und der Prozess abbricht.

Reicht der Wechsel zu Filesystem-Mode für 100 PDFs pro Lauf aus?

In den meisten Single-Instance-Setups ja, weil die Dateien dann auf der Festplatte statt im Arbeitsspeicher liegen und der RAM-Verbrauch pro Ausführung deutlich sinkt. Läufst du im Queue-Modus mit mehreren getrennten Workern, brauchst du zusätzlich entweder gemeinsam genutzten Speicher oder den S3-Modus, weil n8n Filesystem-Mode dort nicht unterstützt.

Brauche ich für S3-Speicher eine bestimmte n8n-Lizenz?

Ja. Laut offizieller Dokumentation ist die S3-Anbindung für Binärdaten an eine gültige Enterprise-Lizenz gebunden, ohne die die Instanz im S3-Modus nicht startet. Für kleinere Setups ohne mehrere Worker-Maschinen ist der kostenlose Filesystem-Modus in der Regel die einfachere und ausreichende Lösung.

Muss ich den Binärdaten-Ordner manuell löschen?

n8n räumt den Ordner nicht automatisch auf, sondern koppelt die Bereinigung an die Ausführungsdaten-Pruning-Einstellungen wie `EXECUTIONS_DATA_PRUNE` und `EXECUTIONS_DATA_MAX_AGE`. Ist Pruning aktiv, werden alte Ausführungen inklusive ihrer Binärdaten im aktiven Modus regelmäßig entfernt, bei deaktiviertem Pruning wächst der Ordner unbegrenzt weiter.