Node-RED MQTT verbindet nicht? Schnell beheben

Wenn Node-RED MQTT nicht verbindet, hängt der Node meist an einem gelben Ring mit "connecting" oder springt zwischen connected und disconnected hin und her, und der Rest Ihres Flows verstummt. Dieser Leitfaden bietet einen schnellen, geordneten Weg zur Ursache: die richtigen Logs lesen, die Erreichbarkeit des Brokers außerhalb von Node-RED nachweisen und dann Ports, TLS, Hostnamen, Client-IDs, Zugangsdaten und Container-Netzwerke durchgehen, bis der Status grün wird. Gerade auf Edge-Gateways in der Fertigung, wo Node-RED Maschinendaten in einen Unified Namespace (UNS) einspeist, steht sonst der gesamte Datenfluss still.

Die Symptome kennen

Der Status unter einem mqtt in- oder mqtt out-Node ist Ihr erster Hinweis:

Status	Was er meistens bedeutet
Gelber Ring, dauerhaft "connecting"	Node-RED kann überhaupt keine Verbindung aufbauen: falscher Host oder Port, TLS passt nicht, Firewall, DNS
Roter Ring, "disconnected"	Der Broker hat die Verbindung abgelehnt oder geschlossen; Zugangsdaten und Logs prüfen
Alle paar Sekunden grün, dann rot	Ein anderer Client verwendet dieselbe Client-ID, oder Keepalive-Probleme
Grün, aber keine Nachrichten	Die Verbindung steht; das Problem liegt bei Topic, QoS oder Publisher
Grau oder kein Status	Der Node ist mit keiner Broker-Konfiguration verbunden, oder der Flow ist nicht deployt

Beachten Sie die letzten beiden Zeilen. Ein grüner Status bedeutet, dass die Verbindung funktioniert; springen Sie dann direkt zu den Topics. Viele Meldungen, MQTT "verbinde nicht", sind in Wahrheit Probleme mit dem Abonnement.

Schritt 1: Das Node-RED-Log lesen

Der Editor zeigt nur einen kurzen Status. Den eigentlichen Fehler enthält das Node-RED-Log. Wo Sie es finden, hängt davon ab, wie Sie Node-RED betreiben:

# Started from a terminal: the log is in that terminal

# Installed as a systemd service (e.g. Raspberry Pi script)
journalctl -u nodered -f

# Docker
docker logs -f nodered

Suchen Sie nach Zeilen des MQTT-Broker-Nodes wie Connection failed to broker: .... Der Text nach dem Doppelpunkt, zum Beispiel Connection refused: Not authorized, getaddrinfo ENOTFOUND, ECONNREFUSED oder ein Zertifikatsfehler, führt Sie direkt zu einem der folgenden Abschnitte.

Schritt 2: Außerhalb von Node-RED testen

Bevor Sie in Node-RED etwas ändern, weisen Sie nach, dass der Rechner den Broker erreicht. Die Mosquitto-Clients sind der schnellste Weg. Probieren Sie zuerst den öffentlichen MQTT-Broker, da er keine Zugangsdaten braucht:

mosquitto_sub -h broker.connectmq.com -p 1883 -i nr-test-6b0e \
  -t "connectmq/demo/6b0e/#" -v

In einem zweiten Terminal:

mosquitto_pub -h broker.connectmq.com -p 1883 -i nr-test-pub-6b0e \
  -t "connectmq/demo/6b0e/ping" -m "hello"

Erscheint hello, funktioniert ausgehendes MQTT von diesem Rechner. Testen Sie nun Ihren privaten Broker genau so, wie Node-RED sich verbinden wird, mit TLS und Zugangsdaten:

mosquitto_sub -h YOUR_BROKER_HOST -p 8883 \
  --capath /etc/ssl/certs \
  -u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID \
  -t "test/#" -v -d

Das Flag -d gibt die Pakete CONNECT und CONNACK aus. Schlägt dieser Befehl fehl, liegt das Problem beim Netzwerk, beim Zertifikat oder bei den Zugangsdaten, nicht bei Node-RED. Gelingt er und Node-RED scheitert trotzdem, vergleichen Sie die Node-RED-Einstellungen Feld für Feld mit diesem Befehl. Beenden Sie den Test-Client, bevor Sie Node-RED starten, denn er verwendet dieselbe Client-ID.

Schritt 3: Server, Port und TLS gemeinsam prüfen

Die meisten Verbindungsschleifen entstehen durch eine Unstimmigkeit zwischen Port und TLS-Einstellungen. Die meisten Broker verwenden diese Standardports:

Port	Transport	Einstellungen im Node-RED-Broker-Node
1883	MQTT über TCP	Use TLS nicht angehakt
8883	MQTT über TLS	Use TLS angehakt
8083	MQTT über WebSocket	Server `ws://host:8083/mqtt`
8084	MQTT über sicheren WebSocket	Server `wss://host:8084/mqtt`

Häufige Fehler:

Port 8883 ohne TLS. Node-RED sendet unverschlüsseltes MQTT an einen TLS-Port; der Broker wartet auf einen TLS-Handshake, und der Node verbindet sich immer wieder neu.
Port 1883 mit angehaktem TLS. Node-RED startet einen TLS-Handshake gegen einen unverschlüsselten Port und scheitert.
Schema im Serverfeld. Tragen Sie für TCP und TLS nur den Hostnamen ein, etwa broker.connectmq.com. Verwenden Sie eine ws://- oder wss://-URL nur, wenn Sie über WebSocket verbinden wollen.
Tippfehler und Leerzeichen. Ein Leerzeichen am Ende des Hostnamens erzeugt DNS-Fehler, die schwer zu entdecken sind.

Prüfen Sie bei TLS außerdem, dass Verify server certificate aktiviert ist und der Servername zum Zertifikat passt. ConnectMQ verwendet ein Let's-Encrypt-Zertifikat, dem Node.js standardmäßig vertraut; Sie müssen also keine CA-Datei hochladen. Haben Sie eine eigene TLS-Konfiguration mit einer alten CA-Datei angelegt, entfernen Sie sie. Die vollständige Einrichtung steht in Node-RED MQTT mit TLS.

Schritt 4: Doppelte Client-IDs ausschließen

MQTT-Broker erlauben pro Client-ID nur eine Verbindung. Verbindet sich ein zweiter Client mit derselben ID, trennt der Broker den ersten. Verbinden sich beide automatisch neu, werfen sie sich endlos gegenseitig hinaus, was sich als Status zeigt, der zwischen connected und disconnected wechselt.

Typische Quellen für Duplikate:

Zwei Node-RED-Instanzen, etwa ein Laptop und ein Raspberry Pi, mit demselben deployten Flow.
Ein laufen gelassenes Test-mosquitto_sub mit der Client-ID von Node-RED.
Ein neu erstellter Docker-Container, während der alte noch läuft.
Zwei Broker-Konfigurations-Nodes in einer Node-RED-Instanz mit derselben ID.

Geben Sie jeder Instanz eine eindeutige ID. Auf dem öffentlichen Broker funktioniert jede nicht leere, eindeutige Zeichenfolge. Bei privaten ConnectMQ-Brokern sind Client-IDs an die ausgegebenen Zugangsdaten gebunden; verwenden Sie also die im Portal angezeigte Client-ID und nutzen Sie diesen Zugangsdatensatz nicht auf einer zweiten Instanz, sondern legen Sie dafür einen weiteren an.

Schritt 5: Zugangsdaten und Kontolimits prüfen

Wird die Verbindung direkt nach dem Verbinden abgelehnt, geht es meistens um die Authentifizierung. Bei MQTT 3.1.1 sehen Sie die Return Codes 4 oder 5 (falscher Benutzername oder falsches Passwort, nicht autorisiert), bei MQTT 5 Reason Codes wie 0x86 oder 0x87. Geben Sie Benutzernamen und Passwort im Tab Security des Broker-Nodes neu ein und deployen Sie. Zugangsdaten werden getrennt von den Flows gespeichert; wer einen Flow auf einem neuen Rechner importiert, übernimmt also die Broker-Einstellungen, aber nicht das Passwort.

Zwei weniger offensichtliche Ursachen:

Wiederholte fehlgeschlagene Logins. ConnectMQ sperrt eine IP-Adresse nach wiederholten fehlgeschlagenen Anmeldeversuchen. Haben Sie ein falsches Passwort deployt und Node-RED hat es viele Male erneut versucht, korrigieren Sie die Zugangsdaten und warten Sie, bis die Sperre aufgehoben ist, bevor Sie schließen, dass auch das neue Passwort falsch ist.
Verbindungskontingente. Jeder Plan hat ein Verbindungslimit; der kostenlose Serverless-Plan erlaubt bis zu 25 Verbindungen. Über dem Limit kann ein MQTT-5-Broker mit dem Reason Code 0x97 (Quota exceeded) ablehnen. Zählen Sie alle Geräte, Dashboards und Node-RED-Instanzen.

Schritt 6: Netzwerk, DNS und Container korrigieren

Zeigt das Log ENOTFOUND, ETIMEDOUT oder ECONNREFUSED:

Firewalls. Firmen- und manche Gastnetze blockieren ausgehend 1883 und 8883. Probieren Sie sicheren WebSocket auf 8084, der oft dort durchkommt, wo reines MQTT scheitert.
Docker-localhost. Innerhalb eines Containers ist localhost der Container selbst. Verwenden Sie den Hostnamen des Brokers, einen Compose-Servicenamen oder host.docker.internal; siehe Node-RED mit Docker.
DNS. Führen Sie auf dem Node-RED-Host nslookup YOUR_BROKER_HOST aus. Gateways mit falsch konfiguriertem DNS scheitern zuerst hier.
Proxys. Der MQTT-Client von Node-RED leitet reines TCP nicht über einen HTTP-Proxy; WebSocket-Verbindungen sind oft proxyfreundlicher.

Schritt 7: Keepalive- und Session-Einstellungen prüfen

Bricht die Verbindung in einem ansonsten gesunden Netz alle ein, zwei Minuten ab, sehen Sie sich den Keepalive an. Ein Wert von 60 Sekunden passt für die meisten Verbindungen. Sehr lange Werte erlauben NAT-Routern, inaktive Verbindungen stillschweigend zu verwerfen. Stellen Sie außerdem sicher, dass die Einstellungen für Clean session und die Protokollversion dem entsprechen, was Ihr Flow erwartet. MQTT-5-Funktionen in einem auf 3.1.1 eingestellten Broker-Node verhindern zwar nicht das Verbinden, können aber seltsames Verhalten danach erklären.

Schnelle Checkliste zur Fehlerbehebung

Ist der Flow deployt und der MQTT-Node mit einer Broker-Konfiguration verknüpft?
Zeigt das Node-RED-Log einen konkreten Fehler?
Verbindet sich mosquitto_sub vom selben Rechner mit denselben Einstellungen?
Passen Port und TLS-Einstellungen zusammen (1883 unverschlüsselt, 8883 TLS)?
Enthält das Serverfeld nur den Hostnamen, ohne Tippfehler?
Ist die Client-ID über alle laufenden Clients hinweg eindeutig?
Sind Benutzername und Passwort korrekt, und ist Ihre IP nicht vorübergehend gesperrt?
Liegen Sie unter dem Verbindungslimit Ihres Plans?
Löst DNS auf, und ist der Port aus diesem Netz oder Container offen?

Ist der Status grün, kommen aber keine Nachrichten an, prüfen Sie Topics und Wildcards und sehen Sie sich im Node-RED-MQTT-Tutorial einen funktionierenden Referenz-Flow an. Die offizielle Dokumentation der Node-RED-MQTT-Nodes erklärt außerdem jede Broker-Einstellung.

Ein Broker, der sich leicht debuggen lässt

Die Fehlersuche geht schneller, wenn Sie die Broker-Seite sehen. ConnectMQ ist ein vollständig verwalteter MQTT-Broker mit einem Portal, das einen MQTT-Client im Browser und einen Live-Topic-Explorer enthält, sodass Sie prüfen können, ob die Nachrichten von Node-RED ankommen. Sie können auch $SYS/broker/connection/{clientId}/state abonnieren, um zu beobachten, ob ein bestimmter Client verbunden ist. Erstellen Sie unter app.connectmq.com einen kostenlosen Serverless-Broker, ohne Kreditkarte, und übernehmen Sie Host, Port, Benutzername, Passwort und Client-ID exakt in Node-RED. Hintergrundwissen bietet der Artikel zur Wahl eines Cloud-MQTT-Brokers.

Häufig gestellte Fragen

Warum hängt mein Node-RED-MQTT-Node bei connecting?

Meist ist Host oder Port falsch, TLS passt nicht zum Port, oder eine Firewall blockiert die Verbindung. Suchen Sie im Node-RED-Log den genauen Fehler und testen Sie dieselben Einstellungen mit mosquitto_sub.

Warum verbindet und trennt sich mein Node-RED-MQTT-Node ständig?

Die häufigste Ursache ist eine doppelte Client-ID: Ein anderer Client mit derselben ID übernimmt immer wieder die Session. Geben Sie jeder Node-RED-Instanz und jedem Test-Tool eine eindeutige Client-ID.

Muss ich ein CA-Zertifikat hochladen, um mich mit ConnectMQ zu verbinden?

Nein. ConnectMQ verwendet ein Let's-Encrypt-Zertifikat, dem Node.js standardmäßig vertraut. Haken Sie Use TLS an, verwenden Sie Port 8883 und lassen Sie die Zertifikatsprüfung aktiviert.

Kann Node-RED sich durch eine Firmen-Firewall mit MQTT verbinden?

Sind die Ports 1883 und 8883 gesperrt, probieren Sie MQTT über sicheren WebSocket auf Port 8084 mit dem Pfad /mqtt, der eher erlaubt ist.

Node-RED MQTT verbindet nicht: Leitfaden zur Fehlerbehebung