!Nahaufnahme einer Raspberry-Pi-Platine mit Chips, USB-Buchsen und Anschlüssen

Im Oktober 2024 eröffnete der Zigbee2MQTT-Entwickler Koenkk auf GitHub eine Diskussion mit dem Titel "Z2M 2.0.0: USB adapter discovery error". Sie war als Hilfestellung gedacht: eine Zeile in die Konfiguration, fertig. Heute stehen dort knapp hundert Kommentare, und der Faden reißt nicht ab. Ein Nutzer mit Synology-NAS und Sonoff-Dongle schreibt, er habe gut acht Stunden gesucht, bis alles wieder lief. Ein anderer ging von Version 2.3.0-1 zurück auf 1.41.0-1 und will dort bleiben, weil "surprisingly everything works". Und ein Dritter kam mit Openhabian nach dem Sprung von 1.43.0 auf 2.6.1 nicht mehr zum Laufen.

Die Ursache war eine Verbesserung. Zigbee2MQTT erkennt den Funkstick selbst und rät nicht mehr, wenn es unsicher ist. Früher nahm es bei Unsicherheit stillschweigend den Treiber zstack an. Das ging bei vielen Installationen jahrelang gut und bei anderen gar nicht, mit einer Fehlermeldung, die auf eine falsche Fährte führte. Seitdem gilt: Wer nicht erkannt wird, muss Adapter und Port selbst eintragen.

Dieser Artikel sortiert die Startfehler nach dem Ort, an dem sie entstehen: Stick, Oberfläche, Konfiguration, MQTT-Broker, Firmware, Netzwerkdaten. Stand: 16. November 2026. Alle Fehlermeldungen und Lösungen stammen aus der Zigbee2MQTT-Dokumentation, dem GitHub-Repository der Home-Assistant-App und den Release Notes von Home Assistant.

Erst die Begriffe: Add-on oder App?

In Anleitungen steht mal "Add-on", mal "App", gemeint ist dasselbe. Home Assistant hat die Add-ons mit Version 2026.2 vom 4. Februar 2026 umbenannt. In den Release Notes heißt es: "Add-ons are now called Apps". Begründet wird das mit Verwechslungsgefahr zwischen "Add-ons" und "Integrations". Apps laufen laut Blog neben Home Assistant, Integrationen verbinden Home Assistant mit Geräten und Diensten. Mosquitto ist das Beispiel aus den Release Notes: Die App liefert den Broker, die MQTT-Integration verbindet Home Assistant damit.

Das Menü heißt jetzt Einstellungen, Apps, App-Store. Die offizielle Installationsanleitung der Z2M-App nutzt die neue Sprache bereits. Ältere Tutorials, Foren und auch die Zigbee2MQTT-Doku sagen weiterhin "add-on". Die Funktion ist dieselbe, nur die Beschriftung weicht ab. Für Websuchen hilft es, beide Wörter zu probieren.

Fehler 1: "No valid USB adapter found"

Die Meldung lautet vollständig USB adapter discovery error (No valid USB adapter found). Specify valid 'adapter' and 'port' in your configuration. Die Fehlerbehebungsseite von Zigbee2MQTT führt sie an erster Stelle und verweist auf den serial-Abschnitt der Konfiguration.

Laut Koenkks Erklärung in der oben genannten Diskussion gilt das ab Version 1.41.0: Erkennt Zigbee2MQTT den Adapter nicht automatisch, müssen port und adapter explizit stehen. Wer vorher unbemerkt auf zstack gefallen war, bekommt jetzt diesen Fehler. Die Doku gibt als Beispiel:

serial:
  adapter: zstack
  port: /dev/ttyACM0

Welcher Wert für adapter stimmt, hängt vom Chip ab. Laut Zigbee2MQTT-FAQ steht zstack für Texas-Instruments-Sticks, ember für Silicon Labs mit EmberZNet. Dazu kommen conbee, ezsp, zboss und zigate. Mit dem falschen Treiber läuft es anders in die Wand: Koenkk nennt in der Diskussion einen EZSP-Stick ohne gesetzten adapter, der mit SRSP - SYS - ping after 6000ms abbricht. Das ist der nächste Fehler auf der Liste. Wie Sie Ihren Stick einordnen, steht im Koordinatorvergleich und in der Stick-Empfehlung.

Der Port: besser by-id als ttyACM0

Die Doku empfiehlt, den Pfad aus /dev/serial/by-id zu lesen. Auf der Kommandozeile:

ls -l /dev/serial/by-id

Die Ausgabe zeigt einen Namen mit Herstellerangabe und einen Verweis auf das echte Gerät, zum Beispiel ttyACM0. Der Port des Sticks kann sich ändern, wenn Sie ihn umstecken oder ein zweites USB-Gerät dazukommt. Genau das steht in der Doku als häufiger Grund für SRSP - SYS - ping after 6000ms: "The port of your serial adapter changed." Der by-id-Pfad bleibt dagegen am Gerät hängen. Das README der Home-Assistant-App nutzt ebenfalls ein by-id-Beispiel.

Wer an seinem Home Assistant keine Konsole hat: Das README der App nennt den Befehl ha hardware info im Home-Assistant-CLI. Sitzt nur ein einziges USB-Gerät am System, probiert man laut README der Reihe nach /dev/ttyACM0, /dev/ttyUSB0 und /dev/ttyAMA0.

Zwei Stolperfallen kommen aus der Praxis der GitHub-Diskussion. Erstens läuft Home Assistant bei manchen in Docker, und der Container sieht den Stick nur, wenn das Gerät durchgereicht wird. Ein Nutzer in der Diskussion löste sein Problem genau so, mit einem Eintrag für das Gerät in der docker-compose.yaml. Zweitens ist YAML penibel bei Einrückungen: Ein Kommentator in der Diskussion hatte laut eigener Aussage die Einrückung mit zwei Leerzeichen geprüft und bekam den Fehler trotzdem. Die Einrückung allein erklärt also nicht jeden Fall, sie gehört aber zur ersten Kontrolle.

Fehler 2: "SRSP - SYS - ping after 6000ms" und Co.

Dieser Fehler hat laut Doku gleich mehrere mögliche Ursachen. Die Liste, die die Zigbee2MQTT-Entwickler selbst führen, ist lang und ungeordnet. Sie zeigt, wie viel hinter dem einen Fehler stecken kann. Die Punkte, die nach einem Update relevant sind:

  • Der Port hat sich geändert (siehe oben).
  • Die ZHA-Integration von Home Assistant ist noch aktiv. Die Doku rät, ZHA zu deaktivieren und die Z2M-App neu zu starten. Wie sich beide Stacks unterscheiden, steht im Vergleich Zigbee2MQTT oder ZHA.
  • Der Stick benötigt zusätzliche Parameter, etwa ConBee II und RaspBee II.
  • Auf dem Stick läuft Router- statt Koordinator-Firmware.
  • Eine andere Software, auch eine Home-Assistant-Integration, greift auf den USB-Port zu.
Für den Fall, dass ein anderes Programm den Port belegt, nennt die Doku zwei Fehlerbilder: Resource temporarily unavailable Cannot lock port und beim EmberZNet-Stack Received unexpected reset from adapter, with reason=RESET_SOFTWARE. Die Empfehlung ist in beiden Fällen dieselbe: Prüfen, wer den Port festhält, und bei Home Assistant die ZHA-Integration abschalten. Zwei Stacks auf einem Stick funktionieren nicht, auch wenn man sie nacheinander einrichtet und nur einen "gerade nicht benutzt".

Dazu kommt Hardware. Die Doku nennt bei Raspberry-Pi-Setups ein schlechtes Netzteil, erkennbar an Zeilen wie Under-voltage detected! in dmesg -w, und defekte Verlängerungskabel mit USB disconnect-Meldungen. Für den Pi 3 steht im README der Home-Assistant-App ein Warnhinweis: Ein Raspberry Pi 4 sollte es mindestens sein, der Pi 3 könne wegen begrenzter Ressourcen zu Instabilität führen.

Fehler 3: "502 Bad Gateway" beim Öffnen der Oberfläche

Das ist der harmloseste und zugleich der verwirrendste Fehler. Das README der Home-Assistant-App sagt dazu in einem Satz: Zeigt die Oberfläche 502: Bad Gateway, dann einfach etwas länger warten und die Seite neu laden. Dauert es länger, etwa mehr als zwei Minuten, soll man in den Log-Reiter der App schauen.

Die Reihenfolge beim Start lässt sich an einem Log ablesen, das im Issue #9004 (unten) zu sehen ist: erst der Funkstick, dann die Geräteliste, dann die Verbindung zum MQTT-Server, zuletzt das Frontend. Ein 502 heißt vermutlich nur, dass hinter der Weiterleitung noch niemand antwortet (Einschätzung, die Doku sagt es nicht so). Wartezeit ist dann normal.

Bleibt es bei 502, liegt der Fehler in der Regel nicht im Frontend, das als Letztes startet. Fehlt die Zeile mit dem Start des Frontends im Log, ist der Fehler weiter vorn zu suchen. Im GitHub-Issue #9004 von 2021 sah ein Nutzer 502 und stellte fest, dass sein Log bei Connecting to MQTT server abbrach, ohne dass je "Connected to MQTT server" oder "Started frontend" erschien. Ein anderer Teilnehmer lieferte zum Vergleich ein vollständiges Log, in dem beide Zeilen vorkommen. Das Issue ist alt, die Methode gilt weiter: Log von oben bis unten lesen und die Stelle finden, an der es endet.

Fehler 4: Konfigurationsfehler nach dem 2.0-Update

Mit Version 2.0.0 hat Zigbee2MQTT viele alte Einstellungen entfernt. Die Liste der Breaking Changes umfasst mehrere Seiten. Die Entwickler schreiben dort, dass die meisten Änderungen Altlasten betreffen, die seit Jahren als veraltet gelten und für neuere Netze ohnehin automatisch abgeschaltet sind.

Es gibt eine Hilfe: ein automatisches Migrationssystem. Laut Doku zur Konfigurationsmigration passt es die configuration.yaml an, legt vorher eine Sicherung unter einem Namen wie data/configuration_backup_v1.yaml an und schreibt ein Protokoll nach data/migration-1-to-2.log. In dem Protokoll stehen Zeilen wie:

[TRANSFER] Baudrate was moved from advanced.baudrate to serial.baudrate.
[REMOVAL] The MQTT legacy API has been removed (advanced.legacy_api setting).

Für Home Assistant stehen in der Doku zwei Einschränkungen.

Erstens wandern Werte aus der App-Konfiguration nicht in die configuration.yaml. Einstellungen, die Sie auf der Konfigurationsseite der Home-Assistant-App oder per Umgebungsvariable gesetzt haben, werden laut Doku nicht in die Datei geschrieben. Das Migrationssystem kann sie deshalb nicht anfassen. Brauchen sie eine Anpassung, ist das Ihre Arbeit. Das passt zum Muster aus dem README der App, in dem Port und MQTT über die App-Oberfläche konfiguriert werden und die Datei nur den Rest enthält.

Zweitens gleicht die Migration Folgen in Home Assistant nicht aus, das steht ausdrücklich in der Doku. Ein Beispiel aus der Liste der Breaking Changes: Zigbee2MQTT lauscht nicht mehr auf hass/status, sondern auf homeassistant/status, sofern homeassistant.status_topic nicht gesetzt ist. Wer in Home Assistant eine abweichende Birth-Message eingestellt hat, sollte laut Liste prüfen, ob das Topic homeassistant/status lautet. Außerdem wurden Entitäten ersetzt: update_state und update_available weichen update-Entitäten, Kindersicherungen sind jetzt Schalter statt Schlösser. Automationen mit den alten Entitäten laufen ins Leere, auch wenn Zigbee2MQTT sauber gestartet ist.

Ein dritter Punkt betrifft die Konfiguration direkt: Die Einstellung permit_join wurde entfernt, Beitrittsmodus gibt es nur noch über Oberfläche oder MQTT, und höchstens 254 Sekunden lang. Wer die Datei von Hand pflegt und noch auf alte Schlüssel baut, schaut ins Migrationsprotokoll.

Die Doku warnt außerdem davor, das Feld version von Hand zu ändern. Das kann die Datei beschädigen und die Migration unbrauchbar machen.

Fehler 5: Der MQTT-Broker ist nicht erreichbar

Zigbee2MQTT braucht einen MQTT-Broker. Fehlt die Verbindung, steht im Log Not connected to MQTT server! und Nachrichten lassen sich nicht senden. Diese Zeilen zeigt die Doku in ihrem Beispiel für Netzwerk-Adapter: Not connected to MQTT server! und Cannot send message: topic: 'zigbee2mqtt/bridge/state'. Dort gelten sie als Hinweis auf ein Netzwerkproblem.

Die MQTT-Seite der Doku beschreibt server, user und password. Für die Mosquitto-App von Home Assistant steht dort ein konkreter Hinweis im Beispielkommentar: Statt localhost benutzt man core-mosquitto. Bleibt dort mqtt://localhost:1883 stehen, zeigt localhost in der App vermutlich auf den eigenen Container und nicht auf Mosquitto. Das ist eine Schlussfolgerung, die Doku nennt nur core-mosquitto als richtigen Wert.

Die Prüfliste:

  1. Läuft die Mosquitto-App? Das README der Z2M-App sieht vor, sie über den App-Store zu installieren und zu starten, bevor man Zigbee2MQTT einrichtet.
  2. Stimmen server, user und password in der Z2M-Konfiguration mit dem Broker überein?
  3. Läuft der Broker im selben Netz? Die Doku sieht bei Zigbee2MQTT auf einem anderen Rechner Not connected to MQTT server! als Hinweis auf Netzwerkprobleme.
Wie MQTT in Home Assistant grundsätzlich lokal eingesetzt wird, zeigt das Beispiel Tibber Pulse lokal per MQTT.

Fehler 6: Firmware des Koordinators

Zwei Dinge aus der Doku gehören hierher. Erstens: Auf dem Stick kann Router-Firmware laufen statt Koordinator-Firmware. Das ist in der Liste der Gründe für SRSP - SYS - ping after 6000ms ausdrücklich aufgeführt. Nach einem Flash-Versuch ist das also einer der ersten Verdächtigen.

Zweitens: Bei den Sticks CC2530 und CC2531 raten die Entwickler zum Neuflashen, weil diese Hardware zum Absturz neigt. Die Doku nennt diese Hardware "outdated" und rät bei häufigen Abstürzen zu einem leistungsfähigeren Adapter.

Die FAQ gibt hier Entwarnung: Ein Update der Koordinator-Firmware verlangt keine erneute Kopplung der Geräte. Auch Updates und Downgrades von Zigbee2MQTT selbst brauchen kein Neu-Pairing. Falls sich Geräte nach dem Flashen nicht steuern lassen, empfiehlt die FAQ: ein paar Minuten warten, damit sich das Netz sortiert, Schaltbefehle senden und das Gerät vom Strom nehmen.

Wer den Stick wechselt, etwa von zstack auf ember, kann mit Pech neu koppeln müssen. Die FAQ sagt, dass es dann "might not" nötig ist und die Ergebnisse variieren. Backup und Wiederherstellung funktionieren laut Doku offiziell nur für zstack und ember, nicht für conbee, ezsp, zboss und zigate.

Fehler 7: Datenbank und Backup passen nicht zusammen

Dieser Fehler macht Angst, ist aber sinnvoll gedacht: startup failed - configuration-adapter mismatch - see logs above for more information. Die Doku erklärt: Er tritt auf, wenn man pan_id, network_key oder ext_pan_id in der Konfiguration ändert. Zigbee2MQTT vergleicht dann die Datei mit dem, was im Stick und in der Sicherung steht, und verweigert den Start.

Im Log stehen vor dem Fehler Zeilen, die Konfiguration und Adapter nebeneinanderstellen, jeweils für PAN ID, Extended PAN ID, Network Key und Channel List. Zwei Wege führen heraus:

  • Die alten Werte zurück in die Konfiguration schreiben. Achtung: Im Log erscheinen Schlüssel als Hexadezimal-Zeichenkette, in der Konfiguration muss ext_pan_id ein Array sein, etwa [0x39,0xaf,...]. Einfach einfügen geht nicht.
  • Die Sicherung coordinator_backup.json im Datenordner löschen. Dann startet Zigbee2MQTT mit den neuen Werten, aber laut Doku müssen alle Geräte neu gekoppelt werden.
Ein Netz mit dreißig Geräten neu zu koppeln ist der Preis, den Sie bei einem Tippfehler im Netzwerkschlüssel zahlen. Deshalb gilt: Netzwerkdaten nur ändern, wenn es sein muss. Das Netzwerk steckt in zwei Orten gleichzeitig, im Koordinator und in den Dateien unterhalb des Datenordners. In der Home-Assistant-App heißt dieser Ordner laut FAQ zigbee2mqtt/ statt data/. Wer das System umzieht, kopiert diesen Ordner und passt den Pfad des Sticks an.

Die Sicherung der Konfiguration gehört in die Home-Assistant-Backups. Wie das aufgebaut wird, zeigt der Artikel zur Backup-Strategie. Vor dem Update einer größeren Zigbee-Version ist ein Backup in der Praxis der einzige Rückweg.

Reihenfolge für den Ernstfall

Wenn die App nicht startet, lohnt eine feste Reihenfolge, die von außen nach innen geht:

  1. Log der App lesen, von Anfang bis Ende. Die Meldung im Log sagt, in welcher Stufe es hakt: Adapter, MQTT oder Konfiguration.
  2. Adapter prüfen: serial.adapter und serial.port gesetzt? Port aus /dev/serial/by-id oder ha hardware info.
  3. ZHA abschalten, falls es noch aktiv ist.
  4. MQTT-Server prüfen: core-mosquitto bei der Mosquitto-App, Benutzername und Passwort richtig.
  5. Migrationsprotokoll data/migration-1-to-2.log (in der App: zigbee2mqtt/migration-1-to-2.log) ansehen, falls das Update von 1.x auf 2.x kam.
  6. Hardware prüfen: Netzteil, Kabel, USB-Hub, Pi 3 oder Pi 4.
  7. Firmware prüfen, falls nach einem Flash-Versuch nichts mehr geht.
  8. Erst als letzte Option zurück auf die alte Version. Die Doku sagt, ein Downgrade von Zigbee2MQTT braucht keine neue Kopplung. Eine bereits migrierte configuration.yaml sollten Sie dabei nicht blind weiterverwenden. Dafür legt die Migration configuration_backup_v1.yaml an.

Einschätzung

Auffällig ist, wie viele Startfehler gar nicht von Zigbee2MQTT kommen. Der Port hat sich geändert, ZHA hält den Stick fest, das Netzteil schwächelt, der Broker heißt anders. Die Software meldet das jeweils, aber mit Meldungen, die auf Außenstehende kryptisch wirken. SRSP - SYS - ping after 6000ms heißt im Kern nur: Der Stick antwortet nicht. Warum, steht in einer Liste mit sieben Möglichkeiten.

Die Diskussion #24364 zeigt, was eine an sich vernünftige Änderung anrichten kann: Sie nützt der Mehrheit, trifft eine Minderheit hart und füllt jahrelang einen Thread. Zwei Gewohnheiten halten das Risiko klein: serial.adapter ausdrücklich eintragen, bevor ein Update kommt, und vor jedem Major-Sprung ein Backup anlegen. Beides ist schnell erledigt und erspart im ungünstigen Fall einen langen Abend.

Und wer ohnehin wackelige Hardware betreibt, einen CC2531 am Pi 3 mit billigem Netzteil, sollte das Update nicht als Ursache verdächtigen, sondern als Anlass nehmen, die Basis zu erneuern.