Dein Node-RED-Flow läuft seit Tagen oder sogar Wochen problemlos. Daten werden verarbeitet, MQTT-Nachrichten verschickt und Geräte reagieren genau so, wie sie sollen.
Und dann passiert es: Irgendetwas funktioniert nicht mehr.
Eine Function Node liefert nicht das erwartete Ergebnis, ein Wert fehlt oder eine Verarbeitung bricht an einer Stelle ab, an der bisher nie Probleme aufgetreten sind. Jetzt beginnt die Fehlersuche – und genau dann stellt sich die Frage: Was ist innerhalb der Function Node eigentlich passiert?
Natürlich könntest du jetzt zusätzliche Debug Nodes in den Flow einbauen, Werte ausgeben und dich Schritt für Schritt durch die Verarbeitung arbeiten. Noch besser ist es jedoch, wenn dein Flow bereits beim Entwickeln auf solche Situationen vorbereitet wurde.
Mit node.debug(), node.warn() und node.error() kannst du Meldungen direkt aus einer Function Node erzeugen. So hinterlässt dein Flow an wichtigen Stellen gezielt Informationen, die dir später bei der Fehlersuche helfen – ohne den Flow erst mit zusätzlichen Debug Nodes umbauen zu müssen.
In diesem Beitrag schauen wir uns an, wie diese Meldungen funktionieren, worin sie sich unterscheiden und wie du sie sinnvoll für die Fehlersuche in deinen eigenen Node-RED-Flows einsetzen kannst.
Node-RED Function Node debuggen – direkt im Code
Wenn du eine Node-RED Function Node debuggen möchtest, musst du nicht zwangsläufig zusätzliche Debug Nodes in deinen Flow einbauen. Innerhalb einer Function Node stehen dir bereits verschiedene Funktionen zur Verfügung, mit denen du Meldungen direkt aus deinem JavaScript-Code heraus erzeugen kannst.
Dazu gehören unter anderem:
node.debug("Debug-Meldung");
node.warn("Warnung");
node.error("Fehlermeldung");
Damit kannst du an wichtigen Stellen in deiner Function Node gezielt Informationen hinterlegen. Das ist besonders praktisch, wenn ein Flow später einmal nicht mehr wie erwartet funktioniert.
node.warn() und node.error() haben dabei noch einen zusätzlichen Vorteil: Die Meldungen werden im Debug-Tab von Node-RED farblich hervorgehoben. Warnungen erscheinen orange, Fehler rot. Dadurch fallen wichtige Meldungen sofort ins Auge und lassen sich leichter von normalen Debug-Ausgaben unterscheiden.
Statt bei einem Problem erst zusätzliche Debug Nodes einzubauen und den Flow erneut anzupassen, können bereits vorhandene Meldungen Hinweise darauf geben, welcher Teil der Verarbeitung ausgeführt wurde und welche Werte dabei vorlagen.
Die drei Funktionen haben dabei unterschiedliche Aufgaben:
node.debug()eignet sich für detaillierte Informationen zur Fehlersuche.node.warn()macht auf ungewöhnliche Situationen aufmerksam und wird orange hervorgehoben.node.error()signalisiert einen tatsächlichen Fehler und wird rot hervorgehoben.
Der große Vorteil: Du kannst deinen Flow bereits während der Entwicklung so vorbereiten, dass er dir im Fehlerfall genau die Informationen liefert, die du zur Analyse benötigst.
Im nächsten Schritt schauen wir uns zuerst node.debug() genauer an – denn genau diese Funktion ist besonders interessant, wenn Debug-Ausgaben im normalen Betrieb nicht permanent sichtbar sein sollen.
Mit node.debug() eine Function Node debuggen
node.debug() ist besonders interessant, wenn du eine Node-RED Function Node debuggen möchtest, ohne deinen Flow dauerhaft mit sichtbaren Debug-Ausgaben zu überladen.
Eine einfache Debug-Meldung sieht zum Beispiel so aus:
node.debug("Verarbeitung gestartet");
Du kannst aber natürlich auch aktuelle Werte ausgeben:
node.debug("Payload: " + JSON.stringify(msg.payload));
Oder gezielt markieren, welche Stelle im Ablauf gerade erreicht wurde:
node.debug("Schritt 2: Daten wurden erfolgreich geprüft");
Der entscheidende Punkt bei node.debug() ist: Diese Meldungen erscheinen nicht automatisch im Debug-Tab des Editors. Sie werden über das Runtime-Logging von Node-RED ausgegeben und sind nur sichtbar, wenn das entsprechende Log-Level aktiviert ist.
Im normalen Betrieb kannst du das Logging also auf einem höheren Level wie info belassen. Deine Debug-Meldungen bleiben dann im Hintergrund.
Tritt später ein Problem auf, kannst du das Log-Level auf debug erhöhen. Dadurch werden die bereits im Flow eingebauten Meldungen sichtbar und liefern dir zusätzliche Informationen darüber, was innerhalb der Function Node passiert ist.
Genau darin liegt der große Vorteil: Du musst den Flow im Fehlerfall nicht erst verändern, neue Debug Nodes einbauen oder zusätzliche Ausgaben ergänzen. Die Informationen sind bereits vorhanden und werden nur dann sichtbar, wenn du sie wirklich brauchst.
Ein typisches Beispiel könnte so aussehen:
node.debug("Starte Verarbeitung");
const wert = Number(msg.payload);
node.debug("Konvertierter Wert: " + wert);
if (isNaN(wert)) {
node.error("Payload konnte nicht in eine Zahl umgewandelt werden", msg);
return null;
}
node.debug("Verarbeitung erfolgreich abgeschlossen");
msg.payload = wert;
return msg;
Im normalen Betrieb bleiben die node.debug()-Meldungen unsichtbar. Wenn jedoch ein Fehler auftritt, kannst du das Debug-Logging aktivieren und genau nachvollziehen, welche Schritte die Function Node bereits durchlaufen hat.
So wird node.debug() zu einer Art eingebauter Diagnosehilfe für deinen Flow.
Log-Level in Node-RED auf debug setzen
Damit Meldungen von node.debug() sichtbar werden, muss das Log-Level von Node-RED auf debug stehen. Standardmäßig läuft Node-RED meist mit dem Log-Level info, weshalb node.debug()-Ausgaben normalerweise nicht erscheinen.
Das Log-Level wird in der Datei settings.js konfiguriert. Der genaue Pfad hängt davon ab, unter welchem Benutzer Node-RED läuft.
In meinem Fall läuft Node-RED als Service auf einem Linux-Server unter root. Deshalb liegt die Konfigurationsdatei hier:
/root/.node-red/settings.js
Bei anderen Installationen kann der Pfad beispielsweise so aussehen:
/home/<benutzer>/.node-red/settings.js
Welches Benutzerverzeichnis Node-RED tatsächlich verwendet, lässt sich auch im Start- bzw. Service-Log erkennen.
In der settings.js findest du den Bereich logging. Dort ist beispielsweise folgendes Log-Level eingetragen:
logging: {
console: {
level: "info"
}
},
Für die Fehlersuche änderst du den Wert auf debug:
logging: {
console: {
level: "debug"
}
},
Da Node-RED bei mir als Service läuft, muss der Dienst anschließend neu gestartet werden:
sudo systemctl restart nodered
Danach werden auch Meldungen ausgegeben, die du innerhalb deiner Function Nodes mit node.debug() erzeugst:
node.debug("Verarbeitung gestartet");
Diese Meldungen findest du im Node-RED Log welches du dir mit dem nachfolgenden Befehl anzeigen lassen kannst:
journalctl -u nodered -f
Node-RED unterstützt mehrere Log-Level:
fatalerrorwarninfodebugtrace
Für den normalen Betrieb kannst du Node-RED weiterhin auf info laufen lassen. Erst wenn du eine detailliertere Fehlersuche benötigst, stellst du temporär auf debug um.
Genau darin liegt der Vorteil von node.debug(): Die Diagnosemeldungen können bereits im Flow vorhanden sein und werden erst sichtbar, wenn du das entsprechende Log-Level aktivierst.
node.warn() – Warnungen direkt im Debug-Tab ausgeben
Während node.debug() vor allem für detaillierte Diagnoseinformationen im Runtime-Log gedacht ist, eignet sich node.warn() für Situationen, auf die du während des Betriebs aufmerksam gemacht werden möchtest.
Eine einfache Warnung erzeugst du direkt innerhalb einer Function Node:
node.warn("Messwert liegt außerhalb des normalen Bereichs");
Die Meldung erscheint anschließend im Debug-Tab von Node-RED und wird dort orange hervorgehoben. Dadurch fällt sie zwischen normalen Debug-Ausgaben sofort auf.
Besonders praktisch ist node.warn(), wenn ein Zustand zwar ungewöhnlich ist, der Flow aber trotzdem weiterlaufen kann.
Ein einfaches Beispiel:
const wert = Number(msg.payload);
if (wert > 100) {
node.warn("Ungewöhnlich hoher Messwert: " + wert);
}
msg.payload = wert;
return msg;
Liegt der Wert über 100, wird eine Warnung ausgegeben. Die Verarbeitung der Message läuft jedoch ganz normal weiter.
Du kannst mit node.warn() nicht nur feste Texte ausgeben, sondern auch aktuelle Werte oder ganze Objekte:
node.warn({
payload: msg.payload,
topic: msg.topic
});
Gerade bei komplexeren Function Nodes kann das hilfreich sein, wenn du bestimmte Zustände im Blick behalten möchtest, ohne gleich einen echten Fehler auszulösen.
Typische Einsatzfälle für node.warn() sind zum Beispiel:
- ein Messwert liegt außerhalb des erwarteten Bereichs
- eine Antwort benötigt ungewöhnlich lange
- optionale Daten fehlen
- ein Ersatzwert oder Fallback wird verwendet
- ein Zustand ist auffällig, verhindert die weitere Verarbeitung aber nicht
Der entscheidende Unterschied zu node.error() ist damit einfach:
node.warn() macht auf ein Problem aufmerksam – node.error() signalisiert einen echten Fehler.
Im nächsten Abschnitt schauen wir uns deshalb an, wie sich mit node.error() Fehler direkt aus einer Function Node erzeugen lassen und wie diese später mit einer Catch Node weiterverarbeitet werden können.
node.error() – echte Fehler aus der Function Node melden
Während node.warn() auf einen auffälligen, aber noch verarbeitbaren Zustand hinweist, ist node.error() für echte Fehler gedacht.
Eine einfache Fehlermeldung sieht so aus:
node.error("Ungültige DHT11-Sensordaten empfangen");
Die Meldung erscheint im Debug-Tab von Node-RED und wird dort rot hervorgehoben. Dadurch ist sofort erkennbar, dass es sich nicht nur um einen Hinweis oder eine Warnung handelt.
Besonders interessant wird node.error(), wenn du zusätzlich die aktuelle Message übergibst:
node.error("Ungültige Sensordaten empfangen", msg);
Damit kann der Fehler später von einer Catch Node aufgegriffen und in einem separaten Fehlerpfad weiterverarbeitet werden.
Das ist beispielsweise sinnvoll, wenn du bei einem Fehler:
- eine Benachrichtigung senden möchtest,
- einen Fehler protokollieren willst,
- einen Ersatzablauf starten möchtest,
- oder den Fehler an einer zentralen Stelle im Flow behandeln möchtest.
Ein typisches Beispiel aus einer Function Node könnte so aussehen:
const temperatur = Number(msg.payload.temperature);
if (isNaN(temperatur)) {
node.error("Temperaturwert ist ungültig", msg);
return null;
}
return msg;
Ist der Temperaturwert ungültig, wird eine Fehlermeldung erzeugt. Durch
return null;
wird die aktuelle Nachricht in diesem Beispiel nicht weiter über den normalen Ausgang der Function Node gesendet.
Wichtig ist also die Unterscheidung:
node.error("Fehler");
erzeugt eine Fehlermeldung.
Mit
node.error("Fehler", msg);
wird zusätzlich die aktuelle Message mit dem Fehler verknüpft, sodass eine Catch Node darauf reagieren kann.
Damit eignet sich node.error() nicht nur zur sichtbaren Ausgabe eines Fehlers, sondern auch als Grundlage für eine strukturierte Fehlerbehandlung innerhalb eines Node-RED-Flows.
Im folgenden Praxisbeispiel kombinieren wir node.debug(), node.warn() und node.error() in einem echten Flow mit einem XIAO ESP32-C6 und einem DHT11-Sensor.
Praxisbeispiel: DHT11-Sensordaten mit Node-RED überwachen
Für ein kleines Praxisbeispiel verwende ich einen Seeed Studio XIAO ESP32-C6, einen DHT11-Sensor sowie eine LED als Statusanzeige.
Der DHT11 ist am GPIO1 angeschlossen, die LED am GPIO0. Der Mikrocontroller liest Temperatur und Luftfeuchtigkeit aus und sendet die Werte anschließend per MQTT an meinen Node-RED-Server. Nach jeder erfolgreich übertragenen Nachricht blinkt die LED kurz auf. README
Die Messwerte werden an folgendes MQTT-Topic gesendet:
sensors/xiao-esp32c6/dht11
Der Payload sieht beispielsweise so aus:
{
"temperature": 23,
"humidity": 45
}
Genau dieses Format erzeugt das MicroPython-Programm direkt aus den Messwerten des DHT11 und veröffentlicht es anschließend per MQTT. main
In Node-RED sieht der grundsätzliche Flow so aus:
Node-RED Flow im JSON Format
[
{
"id": "flow_dht11_debug",
"type": "tab",
"label": "DHT11 Debugging",
"disabled": false,
"info": ""
},
{
"id": "mqtt_dht11_in",
"type": "mqtt in",
"z": "flow_dht11_debug",
"name": "DHT11 Daten",
"topic": "sensors/xiao-esp32c6/dht11",
"qos": "0",
"datatype": "auto-detect",
"broker": "mqtt_broker",
"nl": false,
"rap": true,
"rh": 0,
"inputs": 0,
"x": 90,
"y": 60,
"wires": [
[
"json_dht11"
]
]
},
{
"id": "json_dht11",
"type": "json",
"z": "flow_dht11_debug",
"name": "JSON umwandeln",
"property": "payload",
"action": "obj",
"pretty": true,
"x": 270,
"y": 60,
"wires": [
[
"function_dht11_check"
]
]
},
{
"id": "function_dht11_check",
"type": "function",
"z": "flow_dht11_debug",
"name": "Sensordaten prüfen",
"func": "node.debug(\"Empfangene Sensordaten: \" + JSON.stringify(msg.payload));\n\nconst temperatur = Number(msg.payload.temperature);\nconst luftfeuchte = Number(msg.payload.humidity);\n\nif (isNaN(temperatur) || isNaN(luftfeuchte)) {\n node.error(\"Ungültige DHT11-Sensordaten empfangen\", msg);\n return null;\n}\n\nif (temperatur > 30) {\n node.warn(\"Temperatur zu hoch: \" + temperatur + \" °C\");\n}\n\nnode.debug(\n \"Sensordaten erfolgreich geprüft: \" +\n temperatur + \" °C / \" +\n luftfeuchte + \" %\"\n);\n\nmsg.payload = {\n temperature: temperatur,\n humidity: luftfeuchte\n};\n\nreturn msg;",
"outputs": 1,
"timeout": 0,
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 470,
"y": 60,
"wires": [
[
"debug_dht11"
]
]
},
{
"id": "debug_dht11",
"type": "debug",
"z": "flow_dht11_debug",
"name": "geprüfte Sensordaten",
"active": true,
"tosidebar": true,
"console": false,
"tostatus": false,
"complete": "payload",
"targetType": "msg",
"statusVal": "",
"statusType": "auto",
"x": 680,
"y": 60,
"wires": []
},
{
"id": "mqtt_broker",
"type": "mqtt-broker",
"name": "Mosquitto",
"broker": "localhost",
"port": "1883",
"clientid": "",
"autoConnect": true,
"usetls": false,
"protocolVersion": "4",
"keepalive": "60",
"cleansession": true,
"autoUnsubscribe": true,
"birthTopic": "",
"birthQos": "0",
"birthPayload": "",
"birthMsg": {},
"closeTopic": "",
"closeQos": "0",
"closePayload": "",
"closeMsg": {},
"willTopic": "",
"willQos": "0",
"willPayload": "",
"willMsg": {}
}
]
Die MQTT-In Node lauscht auf:
sensors/xiao-esp32c6/dht11
Da der MQTT-Payload zunächst als JSON-String ankommt, verwende ich anschließend eine JSON Node. Diese ist auf „Konvertieren in JavaScript-Objekt“ eingestellt.
Danach können Temperatur und Luftfeuchtigkeit innerhalb der Function Node direkt über
msg.payload.temperature
und
msg.payload.humidity
ausgelesen werden.
Jetzt kommt der eigentliche interessante Teil: Die Function Node soll nicht nur die Sensordaten verarbeiten, sondern gleichzeitig passende Diagnoseinformationen erzeugen.
const temperatur = Number(msg.payload.temperature);
const luftfeuchtigkeit = Number(msg.payload.humidity);
// Normale Diagnoseinformation
node.debug(
"DHT11 Messung empfangen: " +
temperatur + " °C, " +
luftfeuchtigkeit + " %"
);
// Ungültige Sensordaten
if (
isNaN(temperatur) ||
isNaN(luftfeuchtigkeit) ||
luftfeuchtigkeit < 0 ||
luftfeuchtigkeit > 100
) {
node.error("Ungültige DHT11-Sensordaten empfangen", msg);
return null;
}
// Auffällige Temperatur
if (temperatur >= 30) {
node.warn(
"Hohe Temperatur erkannt: " +
temperatur + " °C"
);
}
// Auffällige Luftfeuchtigkeit
if (luftfeuchtigkeit >= 70) {
node.warn(
"Hohe Luftfeuchtigkeit erkannt: " +
luftfeuchtigkeit + " %"
);
}
node.debug("DHT11-Sensordaten erfolgreich geprüft");
return msg;
Damit entstehen je nach Zustand unterschiedliche Meldungen.
Bei normalen Messwerten werden nur die mit node.debug() erzeugten Diagnoseinformationen geschrieben. Diese sind bei aktiviertem Debug-Log im Runtime-Log von Node-RED sichtbar.
Steigt die Luftfeuchtigkeit beispielsweise auf 74 %, erzeugt die Function Node zusätzlich:
Hohe Luftfeuchtigkeit erkannt: 74 %
Diese Meldung erscheint mit node.warn() orange hervorgehoben im Debug-Tab.
Bei offensichtlich ungültigen Werten, beispielsweise einer Luftfeuchtigkeit von 150 %, wird dagegen ein echter Fehler ausgelöst:
Ungültige DHT11-Sensordaten empfangen
Durch die Übergabe von msg
node.error("Ungültige DHT11-Sensordaten empfangen", msg);
kann dieser Fehler später zusätzlich von einer Catch Node verarbeitet werden.
So zeigt das Beispiel sehr schön den Unterschied zwischen den drei Meldungsarten:
node.debug()dokumentiert den normalen Ablauf.node.warn()weist auf auffällige, aber noch verarbeitbare Werte hin.node.error()kennzeichnet ungültige Daten und beendet in diesem Beispiel die Verarbeitung der Nachricht.
Fazit: Node-RED-Flows schon beim Entwickeln auf die Fehlersuche vorbereiten
Mit node.debug(), node.warn() und node.error() lassen sich wichtige Informationen direkt aus einer Function Node heraus erzeugen. Der größte Vorteil liegt dabei für mich darin, die Fehlersuche nicht erst dann vorzubereiten, wenn bereits ein Problem aufgetreten ist.
Mit gezielten node.debug()-Meldungen kannst du schon während der Entwicklung dokumentieren, welche Schritte innerhalb einer Function Node ausgeführt werden und welche Werte dabei verarbeitet wurden. Im normalen Betrieb bleiben diese zusätzlichen Meldungen im Hintergrund und können bei Bedarf über das Log-Level debug sichtbar gemacht werden.
node.warn() eignet sich dagegen für auffällige, aber noch verarbeitbare Zustände, während node.error() echte Fehler kennzeichnet und sich bei Bedarf mit einer Catch Node weiterverarbeiten lässt.
Das Praxisbeispiel mit dem XIAO ESP32-C6 und dem DHT11 zeigt, wie sich diese drei Meldungsarten sinnvoll kombinieren lassen: normale Messwerte werden protokolliert, auffällige Werte erzeugen eine Warnung und ungültige Sensordaten führen zu einem Fehler.
So entsteht ein Flow, der im Fehlerfall bereits viele der Informationen liefert, die du für die Analyse benötigst – ohne dass du erst zusätzliche Debug Nodes einbauen musst.
Letzte Aktualisierung am: 12. Oktober 2026
