Node-RED Advanced: Subflows & Fehlerbehandlung

Subflows: Code-Wiederverwendung in Node-RED

Wer in Node-RED nach einer Weile komplexere Setups hat, bemerkt schnell: Manche Logik wiederholt sich. Denselben MQTT-Publish-Block, dieselbe Fehlerprüfung, denselben Alert-Mechanismus baust du in Flow Nummer 3, 7 und 12. Subflows sind die Antwort – sie sind wiederverwendbare Flow-Bausteine.

Subflows erstellen und einsetzen

Du erstellst einen Subflow über das Menü in Node-RED. Innen sieht er aus wie ein normaler Flow mit Input- und Output-Nodes. Du definierst, welche Properties (Eingabeparameter) der Subflow akzeptiert. Dann nutzt du den Subflow wie einen normalen Node – er taucht in der Palette auf und kann beliebig oft eingesetzt werden. Änderungen am Subflow wirken sich sofort auf alle Instanzen aus.

Status-Node im Subflow

Die Status-Node zeigt den aktuellen Zustand eines Nodes im Dashboard an – ein kleiner Text unter dem Node-Symbol. Im Subflow nutzt du die Status-Node, um den Laufzustand nach außen zu kommunizieren: "Gesendet", "Fehler", "Warte auf Antwort". So siehst du auf einen Blick, was jede Instanz des Subflows gerade tut, ohne in den Subflow hineinsehen zu müssen.

Pro-Tipp

Benenne Subflows mit einem Präfix nach ihrer Funktion, z.B. sf_mqtt_publish oder sf_alert_handler. So erkennst du im Flow auf Anhieb, welche Nodes Subflows sind und welche Standard-Nodes.

Join-Nodes: Mehrere Inputs synchronisieren

Die Join-Node ist einer der vielseitigsten Nodes in Node-RED – sie wartet auf mehrere Messages und kombiniert sie zu einer. Das ist essenziell, wenn du auf Input von mehreren Sensoren oder Quellen warten musst, bevor du eine Entscheidung triffst. Häufige Fehler entstehen, wenn Timeouts oder msg.parts nicht richtig verstanden werden.

Manueller und automatischer Modus

Im manuellen Modus definierst du exakt, welche Message-Parts du erwartest (z.B. drei Temperaturmessungen von drei Sensoren). Die Join-Node wartet, bis alle drei angekommen sind, und kombiniert sie dann. Im automatischen Modus nutzt du msg.parts – das setzt Split-Node automatisch, wenn du ein Array aufteilst. Die Join-Node wartet dann auf alle Teile, bevor sie weitergeht.

Häufige Fallstricke

Im manuellen Modus ohne expliziten Timeout wartet die Join-Node auf alle konfigurierten Parts. Wenn ein erwarteter Input nicht kommt (weil ein Sensor offline ist), bleibt der Flow stehen – bis ein Neustart oder manueller Reset. Konfiguriere immer einen Timeout, der den Join abbricht und einen Fehler-Output sendet.

Fehlerbehandlung: Catch-Node und Circuit Breaker

Produktive Node-RED-Flows müssen mit Fehlern umgehen können. Wenn ein HTTP-Request scheitert, ein MQTT-Gerät antwortet nicht oder ein Function-Node einen JavaScript-Fehler wirft, soll der Flow nicht stumm scheitern – er soll auf den Fehler reagieren.

Catch-Node: Fehler abfangen

Die Catch-Node ist der generische Error-Handler in Node-RED. Du verbindest sie mit einem oder mehreren Nodes (oder mit "alle Nodes im Flow"). Wenn ein verbundener Node einen Fehler wirft, geht die Message an die Catch-Node statt an den normalen Output. Dort kannst du loggen, benachrichtigen oder einen Fallback-Wert setzen.

Ein häufiges Muster: Catch-Node → Function-Node (der msg.error auswertet) → Telegram-Node (der eine Benachrichtigung sendet) + Inject-Node (der einen Retry-Timer startet). So bekommst du bei jedem unerwarteten Fehler sofort eine Nachricht.

Circuit Breaker Pattern

Wenn ein Service immer wieder fehlschlägt (z.B. ein API-Endpunkt ist down), solltest du nicht endlos retries machen – das überlastet den Service und dein System. Das Circuit-Breaker-Pattern löst das: Nach N Fehlern in T Sekunden "öffnet" der Circuit Breaker und blockiert weitere Requests für eine Wartezeit. Danach lässt er einen Test-Request durch – wenn der erfolgreich ist, schließt der Breaker wieder.

In Node-RED implementierst du das mit einer Kombination aus Catch-Node, Counter in einer Context-Variable und einer Rate-Limit-Funktion.

Wusstest du schon?

Der Function-Node hat direkten Zugriff auf msg.error wenn er in einem Error-Handling-Flow läuft. msg.error.message enthält die Fehlermeldung, msg.error.source zeigt den Node, der den Fehler geworfen hat. So kannst du gezielt auf verschiedene Fehlertypen reagieren.

Context-Variablen: Zustand zwischen Messages speichern

Node-RED-Flows sind standardmäßig zustandslos – jede Message wird unabhängig verarbeitet. Context-Variablen sind die Ausnahme: Sie speichern Werte über Messages hinweg.

Flow-Context vs. Global-Context

Flow-Context ist auf einen einzigen Flow beschränkt – nur Nodes im selben Tab haben Zugriff. Global-Context ist für alle Flows sichtbar. Verwende Global-Context für Dinge, die wirklich überall gebraucht werden (z.B. den aktuellen Energiepreis oder den Anwesenheitsstatus). Flow-Context für alles, was nur im aktuellen Flow relevant ist.

Persistenter Context: Daten über Restarts hinaus speichern

Standardmäßig verliert Node-RED alle Context-Variablen beim Neustart. Wenn du willst, dass Daten überlebt werden (z.B. ein Zählerstand, die letzte bekannte Temperatur oder den letzten Schalterstatus), musst du persistenten Context aktivieren. In der settings.js konfigurierst du das mit dem contextStorage-Eintrag.

FileSystem-Storage speichert Context als JSON-Dateien auf der Festplatte – für hochfrequente Schreibvorgänge ist das langsam. Für Performance-kritische Setups (etwa wenn jede MQTT-Message einen Zähler inkrementiert): Redis-Storage oder nur In-Memory-Context (überlebt Restarts nicht) nutzen.

Pro-Tipp

Verwende Global-Context nicht als Datenbank. Für strukturierte Daten, die persistent bleiben müssen, ist eine echte Datenbank (MariaDB, InfluxDB) besser geeignet. Global-Context ist für temporäre, flüchtige Zustände wie global.heizung.wohnzimmer.soll gedacht.

Performance: Wenn Flows langsam werden

Node-RED auf einem Raspberry Pi 4 oder einem Beelink Mini S12 Pro🛒(öffnet in neuem Tab) läuft problemlos mit hunderten Nodes. Aber wenn Flows sehr viele Messages pro Sekunde verarbeiten oder komplexe JavaScript-Berechnungen ausführen, kann Performance zum Thema werden. Hier sind die häufigsten Optimierungen:

• Rate-Limit-Nodes einsetzen: Wenn ein Sensor jede Sekunde einen Wert sendet, du ihn aber nur alle 5 Sekunden brauchst, schalte eine Rate-Limit-Node dazwischen. Das reduziert die Message-Frequenz drastisch.
• Delay-Nodes statt setTimeout: Nutze die eingebaute Delay-Node statt JavaScript setTimeout in Function-Nodes. Die eingebaute Node ist effizienter und kann Messages queuen.
• Große Payloads vermeiden: Sende nie ganze Arrays oder große Objekte durch den Flow, wenn du nur ein einzelnes Feld brauchst. Extrahiere das Feld in einer Function-Node am Anfang des Flows.
• Komplexe Logik in Function-Nodes isolieren: Statt viele kleine Function-Nodes zu verketten, konsolidiere die Logik in einer einzigen Node. Das reduziert den Overhead.

Node-RED produktiv einsetzen

Subflows, Join-Nodes und Fehlerbehandlung sind nicht nur nette Features – sie sind der Unterschied zwischen einem Bastel-Flow und einer verlässlichen Smart-Home-Automatisierung. Mit persistentem Context und sauberem Performance-Management läuft Node-RED stabil, auch wenn dein System wächst.