> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-de/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md). # Fehlerbehebung Beheben Sie MQTT-Integrationen nach Fehlerphase — Brokerverbindung, TLS, Authentifizierung, Topic-Routing, letzte Daten. Diagnoseabläufe für MQTT-Integrationen auf dem Kilo IoT Server, nach der Stelle geordnet, an der der Fehler sichtbar wird. Arbeiten Sie diese in dieser Reihenfolge ab — die meisten Probleme fallen in eine der ersten drei Phasen, und die Diagnosefolge grenzt die Ursache effizient ein. Bevor Sie die folgenden Phasen durchgehen, lassen Sie sich von der Plattform sagen, in welcher Sie sich befinden. Ein einzelnes stummes Gerät meldet seinen eigenen Zustand auf seiner **Verbindung** Registerkarte — ob der Broker erreichbar ist, ob eine Veröffentlichung auf einem unerwarteten Topic eingegangen ist und ob seine Werte gespeichert wurden; siehe [Gerätediagnose](/kilo-docs-de/kilo-iot-server/devices/device-diagnostics.md). Wenn mehrere Geräte gleichzeitig still werden, öffnen Sie den Bereich des Connectors **Connector-Diagnose** Bereich — **Quellenstatus** fasst das Broker-Abonnement zusammen, **Eingehend** zeigt, was eingeht, und **Aktivität** zeigt den jüngsten Ereignisverlauf des Connectors. Diese Anzeige weist normalerweise direkt auf die Phase hin, mit der Sie beginnen sollten.
The Diagnostics tab of an MQTT connector showing the Connection, Incoming and Activity sections before any device has published
## Phase 1 — Fehler bei der Broker-Verbindung **Symptom:** der Publisher (ein Edge-Gateway, eine Zigbee2MQTT-Instanz, benutzerdefinierte Firmware) meldet, dass er keine Verbindung zum Broker herstellen kann. **Zuletzt empfangene Daten** wird nie aktualisiert. | Fehlermuster | Ursache | Behebung | | -------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Verbindung abgelehnt` / `Netzwerk nicht erreichbar` (Cloud MQTT) | Falscher Host, Port oder Scheme | Prüfen Sie, dass der Publisher `mqtts://` auf Port 1884 verwendet — nicht den Standardport 1883. Kopieren Sie die Broker-URL erneut von der Connector-Seite. | | `Verbindung abgelehnt` / `Netzwerk nicht erreichbar` (External MQTT) | Netzwerkerreichbarkeit | Die Plattform stellt eine Verbindung zu Ihrem Broker her. Prüfen Sie, ob der Broker aus dem öffentlichen Internet erreichbar ist (DDNS-Hostname wird aufgelöst, Portweiterleitung aktiv, Firewall erlaubt den ausgehenden Bereich der Plattform). | | `fehlerhafter TLS-Handshake` / `Zertifikatsprüfung fehlgeschlagen` | TLS-Konfiguration | Bei Cloud MQTT ist das Zertifikat öffentlich vertrauenswürdig — prüfen Sie, ob der Publisher den systemweiten CA-Speicher verwendet. Bei External MQTT prüfen Sie, ob die Dateien CA-Zertifikat, Client-Zertifikat und privater Schlüssel als separate Dateien hochgeladen wurden (nicht eingefügter PEM-Inhalt), und dass der private Schlüssel beim Hochladen unverschlüsselt war. | | `Authentifizierung fehlgeschlagen` / `nicht autorisiert` | Falsche Zugangsdaten | Prüfen Sie Benutzername und Passwort erneut. Bei Cloud MQTT: Wenn das Passwort verloren ging, setzen Sie es in den Connector-Einstellungen zurück (das ursprüngliche kann nicht wiederhergestellt werden). Bei Basic-Authentifizierung auf External MQTT prüfen Sie die Passwortdatei des Brokers. | | `Authentifizierung fehlgeschlagen (JWT)` | Token-Probleme | Prüfen Sie, ob das JWT gültig ist (nicht abgelaufen), mit dem richtigen Schlüssel für den Validator des Brokers signiert wurde und die erforderlichen Claims enthält (Subjekt, Topic-Berechtigungen). | Für speziell per Z2M-Brücke angebundene Setups zeigt das Z2M-Log den Verbindungsstatus explizit an: ``` docker compose logs zigbee2mqtt | grep -E "Connecting|Connected|MQTT|Error" ``` `Mit dem MQTT-Server verbunden` bestätigt die Publisher-Seite. Fehlt diese Zeile, liegt unabhängig davon, was die Plattform anzeigt, ein Fehler der Phase 1 vor. ## Phase 2 — Verbindung erfolgreich, aber Zuletzt empfangene Daten werden nicht aktualisiert **Symptom:** der Publisher meldet eine erfolgreiche Broker-Verbindung. Die Protokolle zeigen erfolgreiche Veröffentlichungen. **Zuletzt empfangene Daten** in der Kilo-Connector-Seite bleibt leer. Bei Cloud MQTT ist das eine Nichtübereinstimmung des Topic-Präfixes. Jedes veröffentlichte Topic muss exakt mit dem Topic-Präfix des Connectors beginnen. Prüfen Sie: * Die Topic-Konfiguration des Publishers verwendet das **vollständige** Topic-Präfix von der Connector-Seite (typischerweise `iot/{org}/{connection}`). * Für Z2M, `mqtt.base_topic` in `configuration.yaml` ist `{Topic prefix}/zigbee2mqtt`. * Für benutzerdefinierte Firmware wird bei jedem Publish-Aufruf das Präfix vorangestellt. Bei External MQTT ist das eine Nicht-Erreichbarkeits- oder Abonnement-Nichtübereinstimmung: * Führen Sie einen einmaligen Test-Publish von einem Host aus aus, der Ihren Broker erreichen kann: ```bash mosquitto_pub -h {broker-host} -p {port} \ --cafile {ca-bundle} \ -u {username} -P {password} \ -t "test/connectivity" -m '{"hello":"world"}' ``` Wenn **Zuletzt empfangene Daten** immer noch nicht aktualisiert wird, kann die Plattform Ihren Broker nicht erreichen. Untersuchen Sie Firewall-Regeln, IP-Zulassungslisten oder abgelaufene Tunneling-Sitzungen, wenn Sie ngrok zum Testen verwenden. * Bei Brokern hinter NAT mit Portweiterleitung prüfen Sie, ob der externe Port offen ist und zum Host-Port des Brokers weitergeleitet wird. Häufige Fehlkonfigurationen sind die Weiterleitung an die falsche Host-IP, das Blockieren der Quell-IP oder eine Firewall-Regel, die die Portweiterleitung überlagert. ## Phase 3 — Zuletzt empfangene Daten werden aktualisiert, aber die Mapping-Registerkarte des Geräts ist leer **Symptom:** der Connector empfängt Nachrichten (Zuletzt empfangene Daten sind aktuell), aber die Spalte Wert auf der Mapping-Registerkarte eines registrierten Geräts zeigt nichts an. Zwei Ursachen sind häufig: * **Das Device-ID-Topic-Muster stimmt nicht mit dem Publish-Topic überein.** Prüfen Sie das Muster, indem Sie es Byte für Byte mit einem Topic aus den Protokollen des Publishers vergleichen. Häufige Fehler: führender Schrägstrich, fehlende Zwischenabschnitte, abweichende Groß-/Kleinschreibung, abweichende Pluralform (`Messgerät` vs. `Messgeräte`). * **Die Device-ID stimmt bytegenau nicht mit dem extrahierten Abschnitt überein.** Die Entfernung von Leerzeichen im Device-ID-Eingabefeld ist hier der stille Killer. Wenn das Topic des Publishers `plant-3/line-a/EM 4492/data` (enthält ein Leerzeichen) und die Device-ID als `EM 4492`eingegeben wurde, hat die Plattform einen normalisierten String gespeichert, der nicht mehr passt. Entfernen Sie Leerzeichen aus Gerätekennungen — verwenden Sie Bindestriche oder Unterstriche. Erstellen Sie den Gerätedatensatz mit der normalisierten Kennung neu. Um zu verifizieren, was der Publisher tatsächlich sendet: ```bash # Für Z2M: docker compose logs zigbee2mqtt | grep "MQTT publish" | grep -v bridge | tail -5 # Für andere Gateways: direkt beim Broker abonnieren mosquitto_sub -h {broker} -p {port} -t '#' -v ``` Das in diesen Ausgabezeilen angezeigte Topic ist das Topic, mit dem Ihr Device-ID-Topic-Muster und das Device-ID-Feld übereinstimmen müssen. ## Phase 4 — Spalte Wert der Mapping-Registerkarte wird aktualisiert, aber die Logs-Registerkarte ist leer **Symptom:** Öffnen Sie ein registriertes Gerät. Auf der Mapping-Registerkarte werden Live-Werte und Zeitstempel der letzten Aktualisierung angezeigt. Die Logs-Registerkarte ist leer. Dies ist die häufigste betriebliche Verwirrung bei der Inbetriebnahme eines neuen MQTT-Geräts. Die beiden Registerkarten lesen aus unterschiedlichen Speichern: * **Spalte Wert der Mapping-Registerkarte** = Live-Schnappschuss der zuletzt empfangenen Nutzlast. Aktualisiert sich bei jeder akzeptierten Veröffentlichung, unabhängig davon, ob Connector-Schlüssel ausgefüllt sind. * **Protokolle-Tab** = Verlauf pro Sensor, wird nur durch empfangene Veröffentlichungen gefüllt *nach* gespeichert sind. Wenn die letzte Veröffentlichung eintraf, bevor die Connector-Schlüssel gespeichert wurden, gelangt diese Veröffentlichung nie in die Logs. Ältere Veröffentlichungen werden nicht nachträglich normalisiert. Behebung: Erzeugen Sie nach dem Speichern der Connector-Schlüssel eine neue Veröffentlichung. Methoden: * **Warten Sie auf den nächsten geplanten Bericht des Geräts** — bei Sensoren mit periodischem Veröffentlichungsrhythmus. * **Lösen Sie am Gerät eine Zustandsänderung aus** — bei Aktoren mit COV-bei-Zustandsänderung-Semantik. * **Senden Sie eine Poll-Anfrage vom Gateway aus** — für Gateways mit einem `/get`-ähnlichen Lese-Poll-Mechanismus. * **Senden Sie eine Testveröffentlichung von der Broker-Seite aus** — für Entwicklungsszenarien, `mosquitto_pub` an das Topic des Geräts mit einer repräsentativen Nutzlast. Nachdem mindestens eine Veröffentlichung nach dem Speichern eingegangen ist, füllt sich die Logs-Registerkarte und empfängt weiterhin nachfolgende Nachrichten. ## Phase 5 — null-Werte in der Spalte Wert der Mapping-Registerkarte **Symptom:** Die Connector-Schlüssel sind zugeordnet, die Logs-Registerkarte empfängt Daten, aber bestimmte Messwerte werden in der Mapping-Registerkarte als null angezeigt. Die häufigste Ursache: Der Typ der Metrikvorlage stimmt nicht mit dem Typ des veröffentlichten Werts überein. Zum Beispiel führt das Zuordnen eines Z2M `Status` Feld (`"ON"`/`"OFF"` Zeichenfolgen) zu einer Metrikvorlage vom Typ Boolean zu null-Werten — die Plattform kann die Zeichenfolge nicht als Booleschen Wert parsen. Prüfen Sie den [Übersetzung von Payload-Typ → Metriktyp](/kilo-docs-de/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md#payload-type--metric-type-translation): * Als Zeichenfolge kodierte Enums (z. B. `"OPEN"`/`"CLOSED"`, `"ON"`/`"OFF"`) → **String**, nicht Boolean. * Z2M `binäre` Funktionen → String. Z2M `numerische` Funktionen → Number. Z2M `Enum-Funktionen → String.` Funktionen → String. Behebung: Bearbeiten Sie die Metrikvorlage (oder ersetzen Sie die Mapping-Zeile durch eine Zeile mit dem richtigen Vorlagentyp), damit der Typ mit dem tatsächlichen Typ des Nutzlastwerts übereinstimmt. ## Phase 6 — Inkonsistente oder doppelte Messwerte über mehrere Geräte hinweg **Symptom:** zwei Gerätedatensätze scheinen die Telemetrie des jeweils anderen zu erhalten, oder ein einzelnes Gerät zeigt abwechselnde Werte aus verschiedenen Quellen. Dies ist eine Kollision des Device-ID-Topic-Musters. Wenn zwei Geräte an Topics veröffentlichen, die beide zu unterschiedlichen `{{deviceId}}` Werten zu einem einzigen Device-ID-Topic-Muster passen, aber das Device-ID-Feld in einem Gerätedatensatz zu beiden passt, werden beide Veröffentlichungen an diesen Datensatz weitergeleitet. Prüfen Sie: * Jeder Gerätedatensatz hat eine eindeutige Device-ID. * Topics auf der Publisher-Seite erzeugen eindeutige Werte an der `{{deviceId}}` Platzhalterposition. * Kein Publisher ist so konfiguriert, dass er unter der Kennung eines anderen Geräts veröffentlicht. ## Zurücksetzen von Cloud-MQTT-Zugangsdaten Wenn eine Zugangsdatenrotation erforderlich ist: 1. Öffnen Sie die Detailseite des Connectors. 2. Erzeugen Sie im Bearbeitungsmodus das Passwort neu. 3. Notieren Sie das neue Passwort sofort; das ursprüngliche kann nach der Neugenerierung nicht wiederhergestellt werden. 4. Aktualisieren Sie alle Publishing-Clients (Firmware-Konfiguration, Z2M `configuration.yaml`, Edge-Gateway-Konfiguration) mit dem neuen Passwort. 5. Starten Sie die Publisher neu, damit die Rotation übernommen wird. Benutzername und Topic-Präfix ändern sich bei der Rotation nicht. ## Zurücksetzen von External-MQTT-Zugangsdaten Bei Basic-Authentifizierung ändern Sie das Passwort auf der Broker-Seite und aktualisieren Sie die Authentifizierungskonfiguration des Connectors. Bei Zertifizierung (TLS-Client-Zertifikat) stellen Sie das Client-Zertifikat neu aus und laden Sie es erneut hoch. Bei JWT generieren Sie das Token neu und aktualisieren Sie den Connector. In allen Fällen gibt es keinen Plattform-seitigen Ablauf zum Rotieren von Zugangsdaten — die Zugangsdaten liegen auf dem Broker; die Plattform speichert nur eine Referenz. ## Wohin als Nächstes * [Topics und Geräte-Routing](/kilo-docs-de/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md) — für Details zur Routing-Konfiguration. * [Externes MQTT](/kilo-docs-de/kilo-iot-server/connectors/mqtt-connector/external-mqtt.md) — für die Broker-seitige Konfiguration selbst gehosteter Broker. * [MQTT-Edge-Gateways](/kilo-docs-de/kilo-iot-server/gateways/mqtt-edge-gateways.md) — für Integrationsmuster industrieller Edge-Gateways (unter Gateways). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kiloiot.io/kilo-docs-de/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.