Eine MQTT-Automation kann erfolgreich aussehen, obwohl etwas anderes dahintersteckt. Vielleicht ist noch eine Benachrichtigung von einem früheren Durchlauf zu sehen, oder jemand hat auf „Aktionen ausführen“ geklickt. Vielleicht wurde eine Retained-Nachricht zugestellt, als sich ein Subscriber verbunden hat. Nichts davon beweist unbedingt, dass deine Testnachricht die Automation ausgelöst und zur erwarteten Aktion geführt hat.
Genau das lässt sich mit dem Automation-Trace von Home Assistant prüfen. Er zeichnet einen Durchlauf auf und zeigt, wie Home Assistant den Trigger, die Bedingungen und die Aktionen ausgewertet hat. Schau dir den Trace zusammen mit einem bewusst harmlosen MQTT-Test an. Er ist keine allgemeine Zustandsbewertung für einen Broker oder ein Gerät. Diese Anleitung verwendet eine erfundene Nachricht und eine dauerhafte Benachrichtigung, damit ein fehlgeschlagener Test keine Folgen für den Betrieb hat. Verwende nur einen Broker und eine Home-Assistant-Instanz, die du selbst administrierst.
Die überprüfbare Aussage hinter dem Trace-Test
Schreib vor dem Öffnen der Trace-Ansicht auf, welche Aussage du prüfen willst. Zum Beispiel: „Eine Nachricht auf lab/trace-check/event, deren event_type auf new_device gesetzt war, hat diese Automation dazu gebracht, eine Benachrichtigung zu erstellen.“ Damit hast du neben der Automation und ihrer Aktion auch ein konkretes Topic und einen Payload-Wert zum Abgleichen.
Mit einer konkreten Aussage verhinderst du, dass du aus „MQTT funktioniert“ mehr ableitest, als der Test hergibt. Ein erfolgreicher Durchlauf zeigt, dass ein bestimmter konfigurierter Ablauf zu einem bestimmten Zeitpunkt funktioniert hat. Er beweist weder, dass ein echtes Gerät vorhanden ist, noch dass sich jeder Publisher wieder verbindet oder der Broker künftige Nachrichten genau einmal zustellt. Die Quality-of-Service-Einstellungen von MQTT beschreiben, wie Clients und Broker mit der Zustellung umgehen. Sie machen aus einem einzelnen Trace keine Langzeitmessung der Zuverlässigkeit.
Wenn ein unbekannter Geräteeintrag der Anlass für deinen Test ist, prüfe Gerätebestand und Automation getrennt. Alle Geräte in deinem Netzwerk und ihre IP-Adressen finden beschreibt, wie du Router-Einträge und lokale Beobachtungen vergleichst, bevor du einem Gerät eine Identität zuordnest. Ein Automation-Trace kann nicht klären, wem ein Gerät gehört.
Eine eindeutig erfundene Testnachricht
Reserviere ein Topic, das du nicht mit dem Topic einer produktiven Integration verwechselst, etwa lab/trace-check/2026-11-03/event. Verwende ein Datum oder eine kurze Testkennung. Vermeide Namen, die mit einem NAS, einem Sensor oder einer Alarmregel kollidieren könnten. Lass Zugangsdaten, private Adressen, Kundennamen und echte Kennungen aus deinem Haushalt aus dem Beispiel heraus.
Verwende einen kleinen JSON-Payload, der klar als Test erkennbar ist:
~~~json { "event_type": "new_device", "name": "Tutorial sensor", "note": "fictional trace test" } ~~~
Name und Notiz sind absichtlich erfunden. Sie belegen weder ein neues Gerät noch einen Sicherheitsvorfall. Um den Ablauf für ein Ereignis zu prüfen, veröffentliche die Nachricht einmal ohne Retain-Option. Eine Retained-Nachricht kann sinnvoll sein, um einen aktuellen Wert bereitzuhalten. Ihr Empfang nach einer erneuten Verbindung eines Subscribers prüft aber etwas anderes als der Empfang eines gerade neu erzeugten Ereignisses.
Notiere den Veröffentlichungszeitpunkt und das genaue Topic. Wenn du eine bekannte Nachricht mit dem Trace abgleichen kannst, musst du deutlich weniger auseinanderhalten.
Der Trigger vor der Aktion
Öffne die Automation in Home Assistant und prüfe, ob sie aktiviert ist. Öffne dann die Trace-Ansicht für den Durchlauf, der nach deiner Testnachricht entstanden ist. Im Trigger-Abschnitt sollte der MQTT-Trigger zu sehen sein, der den Durchlauf gestartet hat. Vergleiche sein Topic Zeichen für Zeichen mit dem notierten Topic. Bei MQTT-Topics zählt die Groß- und Kleinschreibung. /event am Ende statt /events bedeutet einen anderen Pfad.
Wenn es zum erwarteten Zeitpunkt keinen Trace gibt, fang beim Trigger an. Ändere die Aktion noch nicht. Prüfe den ausgewählten Broker und das genaue Topic. Stelle außerdem sicher, dass du die Testnachricht erst nach dem Aktivieren der Automation veröffentlicht hast. Ein manueller Durchlauf über „Aktionen ausführen“ führt die Aktionssequenz ohne MQTT-Trigger-Daten aus und überspringt die Bedingungen auf der obersten Ebene der Automation. Bedingungen innerhalb der Aktionssequenz gelten weiterhin. Er umgeht den MQTT-Trigger und belegt deshalb nicht, dass die Nachricht angekommen ist.
Wenn ein Trace vorhanden ist, prüfe die Trigger-Daten, statt dich auf den Benachrichtigungstext zu verlassen. Kontrolliere, ob der Payload das erfundene JSON enthält, das du gesendet hast, und ob der erwartete Wert im richtigen Feld steht. Ungültiges JSON oder ein fehlendes Feld können verhindern, dass ein Template oder ein Payload-Abgleich passt. Das gilt auch für einen Wert mit abweichender Groß- und Kleinschreibung.
Jede Bedingung im Durchlauf
Bedingungen erklären, warum eine Automation ausgelöst werden kann und trotzdem vor der Aktion stoppt. Klappe im Trace jede Bedingung auf und lies nach, welche Eingabe Home Assistant ausgewertet hat. Dass der Editor das YAML akzeptiert, heißt noch nicht, dass die Bedingung erfüllt war.
Für einen MQTT-Trigger ist eine bewusst eng gefasste erste Testbedingung sinnvoll: event_type muss new_device sein. Veröffentliche einen zweiten erfundenen Payload, bei dem event_type auf device_offline gesetzt ist. Wenn kein neuer Trace erscheint, prüfe, ob ein Payload-Filter im Trigger die Nachricht abgewiesen hat. Ein fehlender Trace allein beweist das nicht. Wenn der Trace einen Durchlauf zeigt, der an der Bedingung stoppt, erkennst du die Trennung deutlich.
Keines der beiden Ergebnisse ist für sich genommen ein Fehler. Prüfe, ob das Verhalten zu deiner Testaussage passt. Ein Test mit einem passenden und einem nicht passenden Testfall kann fehlende oder zu großzügige Payload-Filter erkennen lassen, bevor eine echte Nachricht eine Warnung, einen Schalter oder eine andere Aktion mit Folgen erreicht.
Die Aktion und ihr sichtbares Ergebnis
Prüfe die Aktion erst, wenn der Trace zeigt, dass der Trigger und die Bedingungen gepasst haben. Verwende für den ersten Test eine dauerhafte Benachrichtigung, einen Logbucheintrag oder einen eigens dafür angelegten Helfer. Diese Ergebnisse sind sichtbar und lassen sich rückgängig machen. Solange du den grundlegenden Ablauf noch nicht verstanden hast, lass Schlösser, Alarmanlagen, die Steuerung der Stromversorgung, Netzwerkänderungen und Aktionen außen vor, die Personen außerhalb des Tests benachrichtigen.
Der Aktionseintrag im Trace sollte zeigen, ob Home Assistant den vorgesehenen Dienst aufgerufen hat. Vergleiche den Zeitstempel mit dem der Benachrichtigung oder der Aktualisierung des Helfers. Wenn die Aktion verzeichnet ist, das sichtbare Ergebnis aber fehlt, prüfe das Ziel der Aktion oder die Dienstdaten. Eine sichtbare Benachrichtigung ohne passende Aktion in diesem Durchlauf könnte von einem früheren Durchlauf übrig sein.
Wenn Nachrichten kurz hintereinander eintreffen, spielt der Automationsmodus eine Rolle. Eine Automation im Modus single kann einen neuen Trigger ignorieren, während ein vorheriger Durchlauf noch aktiv ist. Die Modi queued und parallel verhalten sich anders. Ändere den Modus nicht nur, damit ein einzelner Test erfolgreich aussieht. Prüfe zuerst, ob der erwartete Testdurchlauf angenommen wurde und was der Trace dazu aufzeichnet.
Retained-Zustand und erneute Verbindungen als eigene Tests
Ein MQTT-Broker kann eine Nachricht für spätere Subscriber speichern, und Clients können sich nach einem Verbindungsabbruch erneut verbinden. Beides kann dazu führen, dass in einer neuen Home-Assistant-Sitzung ältere Daten auftauchen. Der Trace zeichnet den Automationsdurchlauf auf. Für sich genommen belegt er aber nicht, wann ein Publisher einen als Retained gespeicherten Wert ursprünglich erzeugt hat.
Verwende für den ersten Trace-Test ein nur einmal genutztes Topic und veröffentliche ohne Retain-Option. Teste Retained-Zustand und Verfügbarkeit später getrennt. Halte dabei die Broker-Einstellung und die Verbindungszeitpunkte des Subscribers fest. So bleiben die einzelnen Feststellungen getrennt: Eine Automation hat eine Nachricht verarbeitet, die Verfügbarkeit einer Entität hat sich geändert, und ein Publisher hat ein neues Geräteereignis erzeugt. Wenn du das vermischst, wird die spätere Fehlersuche unnötig unklar.
Auch eine vorhandene MQTT-Discovery-Entität beweist nicht, dass ihre Werte aktuell sind. Prüfe die Entität und ihren Zustand, bevor du sie mit einer Automation verbindest, die Folgen für den Betrieb hat. Der Trace kann dann zeigen, ob die Automation die vorgesehene Entität oder Nachricht erfasst hat. Eine weiterhin sichtbare Dashboard-Karte würde dir das nicht sagen.
Ein kurzes Protokoll des Trace-Tests
Halte außerhalb des Traces kurz fest: Automationsname, reines Test-Topic, erfundener Payload, Veröffentlichungszeitpunkt, Zeitpunkt des Trace-Durchlaufs und Ergebnis der Aktion. Lass Geheimnisse und echte Gerätedaten weg. Damit hat jemand eine Grundlage, um den Test nach einem Update oder Broker-Neustart zu wiederholen, statt nur einen einmaligen Check.
DeviceShelf Server kann Netzwerkbeobachtungen über MQTT Discovery an eine Home-Assistant-Installation veröffentlichen, die du administrierst. Ein Automation-Trace dieser Ausgabe belegt etwas über einen einzelnen konfigurierten Nachrichtenpfad. Gleiche das Ergebnis unabhängig davon mit Router-Einträgen und dem ursprünglichen Dienst ab. Der Trace garantiert weder Geräteidentität noch Verfügbarkeit, Zustellung oder den Ausgang künftiger Automationsdurchläufe.
Entferne die Test-Automation, den Helfer und gespeicherte Retained-Testdaten, wenn du den Check nicht mehr brauchst. Halte die Schlussfolgerung eng gefasst: Zu einem dokumentierten Zeitpunkt hat eine erfundene MQTT-Nachricht diese Home-Assistant-Automation bis zur beobachteten Aktion gebracht. Das reicht, um das nächste Problem einzugrenzen, ohne mehr zu behaupten, als die Ergebnisse belegen.