WLED und Home Assistant: Häufige Probleme und Lösungen
Lösungen für die WLED-Integration in Home Assistant: nicht gefunden, 'Unknown error occurred', nicht verfügbare Entitäten, geänderte IP, fehlende Szenen und Szenenfolgen, Segmente als Entitäten und Firmware-Updates.
Home Assistant hat eine eingebaute WLED-Integration, und meist funktioniert sie ohne Aufwand: Sie findet das Licht, legt eine Licht-Entität und eine Handvoll Steuerelemente an und bleibt synchron. Wenn nicht, ist die Ursache meist eine von wenigen, und mehrere davon wurden in jüngeren Home-Assistant-Versionen behoben. Die erste Frage ist also immer: Welche Home-Assistant-Version haben Sie? Diese Seite nennt zu jedem Verhalten die Version, die es geändert hat.
Die Einrichtung der Integration von Grund auf ist in der offiziellen Dokumentation gut beschrieben. Diese Seite behandelt, was schiefgeht.
Was die Integration anlegt
Wer weiß, was zu erwarten ist, erkennt "fehlende" Entitäten leichter. Für jedes WLED-Licht bekommen Sie:
| Entität | Was sie ist |
|---|---|
| Light | Das Licht selbst, mit Farbe, Helligkeit und einer Effektliste. Bei mehr als einem Segment ein Licht pro Segment |
| Main light | Nur bei mehr als einem Segment (oder mit eingeschaltetem Keep Main Light): Ein/Aus und Gesamthelligkeit für das ganze Gerät |
| Selects Preset und Playlist | Eine Szene laden oder eine Szenenfolge starten |
| Select Color palette | Pro Segment, unter Konfiguration |
| Select Live override | Off, On oder Until device restarts (dasselbe wie das Live-Data-Override von WLED) |
| Zahlenwerte Speed und Intensity | Pro Segment, die Effektregler |
| Schalter | Nightlight, Sync send, Sync receive sowie pro Segment Reverse und Freeze |
| Sensoren | Estimated current, Max current, LED count, IP. Uptime, freier Speicher und die WLAN-Sensoren existieren, sind aber standardmäßig deaktiviert |
| Restart-Taste und Firmware-Update | Unter Konfiguration und Diagnose |
Die Integration braucht WLED 0.14.0 oder neuer. Auf älterer Firmware scheitert die Einrichtung. Seit Home Assistant 2025.12 meldet sie das klar; davor erschien ein allgemeiner Fehler.
WLED wird von Home Assistant nicht gefunden
Home Assistant findet WLED über mDNS (zeroconf, der Dienst _wled._tcp). Unter Discovered (in der deutschen Oberfläche: Entdeckt) erscheint nichts, wenn:
- Das Licht und Home Assistant in verschiedenen VLANs oder Subnetzen sind. mDNS überquert keine Subnetze, es sei denn, Ihr Router oder ein Reflektor leitet es weiter. Das ist der häufigste Grund in Netzwerken mit separatem IoT-VLAN.
- Der mDNS-Name von WLED leer ist. Unter Config›WiFi & Network (WiFi Setup vor WLED 16) muss das Feld mDNS address einen Namen haben (der Standard sieht aus wie
wled-abcdef). Leer bedeutet gar kein mDNS. - Ihr Access Point WLAN-Clients isoliert (oft Client- oder AP-Isolation genannt, üblich in Gastnetzen).
- Die eigenen Netzwerkeinstellungen von Home Assistant die Schnittstelle ausschließen, an der das Licht hängt.
Sie brauchen die Gerätesuche nicht. Fügen Sie die Integration von Hand hinzu: Settings›Devices & services›Add integration›WLED (in der deutschen Oberfläche: Einstellungen > Geräte & Dienste > Integration hinzufügen), und tippen Sie die IP-Adresse des Lichts ein. Neuere Versionen akzeptieren auch eine eingefügte URL und behalten nur den Host.
Wenn Sie die IP nicht kennen: Die WLED-Weboberfläche zeigt sie unter Info, Ihr Router listet sie, und in WLED Max steht sie im Abschnitt Geräteinfo der Einstellungen eines Lichts als IP-Adresse.
"Unknown error occurred" beim Hinzufügen von WLED
Bis Home Assistant 2026.9 erkannte die Einrichtung nur zwei Probleme: "can't connect" und (ab 2025.12) "firmware too old". Alles andere endete als Unknown error occurred (Unbekannter Fehler). In der Praxis war "alles andere":
- Eine beschädigte Szenendatei auf dem Licht. Die Integration liest die Szenen des Lichts bei der Einrichtung, und ungültiges JSON in
presets.jsonließ sie scheitern. Das ist die Ursache in den meisten Berichten. Sichern Sie, was Sie können, und reparieren Sie die Szenen; siehe WLED-Szenen werden nicht gespeichert oder Fehler 12 und WLED sichern. Wenn bei Ihnen ein Werksreset geholfen hat, dann aus demselben Grund: Der Reset löscht die defekte Datei. - Etwas an dieser Adresse, das kein WLED ist, oder ein WLED, das mit einer Fehlerseite antwortet, zum Beispiel während es gerade neu startet.
- Firmware älter als 0.14 auf Home-Assistant-Versionen vor 2025.12.
Home Assistant 2026.10 ersetzt die vage Meldung durch "The device didn't respond like a WLED device" (Das Gerät hat nicht wie ein WLED-Gerät geantwortet), was auf dieselben Ursachen hinweist.
Öffnen Sie http://<light-ip>/json und http://<light-ip>/presets.json in einem Browser. Lädt eine der beiden nicht oder sieht nicht wie sauberes JSON aus, hat auch Home Assistant Probleme damit.
WLED-Entitäten nicht verfügbar
"Nicht verfügbar" bedeutet je nach Entität etwas anderes:
- Alles nicht verfügbar. Home Assistant erreicht das Licht nicht. Prüfen Sie, ob es online ist (öffnen Sie seine Weboberfläche) und ob sich seine IP nicht geändert hat (nächster Abschnitt).
- Nur das Main light. Das Licht hat jetzt ein einziges Segment. Das Main light existiert nur, solange es zwei oder mehr Segmente gibt, und es bleibt als nicht verfügbar in der Entitätenliste, wenn Sie wieder auf ein Segment zurückgehen. Schalten Sie Keep Main Light ein, wenn Sie oft Segmente hinzufügen und entfernen (unten).
- Segment-Lichter, Segment-Geschwindigkeit, Palette, Reverse oder Freeze. Dieses Segment existiert nicht mehr. Home Assistant löscht Segment-Entitäten nie von selbst; entfernen Sie Überbleibsel von Hand.
- Select Preset oder Playlist. Das Licht hat keine Szenen oder keine Szenenfolgen. Speichern Sie eine, und das Select erscheint.
Auf ESP8266-Lichtern mit vielen Effekten und Paletten wurde früher gelegentlich das ganze Gerät als nicht verfügbar angezeigt, weil die große /json-Antwort des Lichts abgeschnitten wurde. Home Assistant 2026.10 liest Effekte und Paletten getrennt und hat das behoben. Seitdem setzt auch eine defekte Szenendatei nicht mehr das ganze Gerät auf nicht verfügbar.
WLED hat die IP-Adresse geändert
DHCP kann dem Licht nach einem Router-Neustart oder einem langen Stromausfall eine neue Adresse geben. Was dann passiert, hängt von Ihrer Version ab:
- Funktioniert die Gerätesuche, bemerkt Home Assistant die neue Adresse und aktualisiert sie selbst. Seit 2026.10 prüft es zuerst, ob das Gerät an der neuen Adresse dieselbe MAC-Adresse hat, was auch einen Fehler beseitigt hat, bei dem eine manuell korrigierte Adresse eine halbe Stunde später zurückgesetzt wurde.
- Kann die Gerätesuche das Licht nicht sehen (anderes VLAN), nutzen Sie Reconfigure (Neu konfigurieren) am WLED-Integrationseintrag und tippen die neue IP ein. Stimmt die MAC nicht überein, lehnt Home Assistant die Änderung ab ("MAC address does not match"); das ist eine Sicherheitsprüfung, kein Fehler.
Die dauerhafte Lösung ist eine DHCP-Reservierung für jedes WLED-Licht in Ihrem Router. Statische IPs in den WLAN-Einstellungen von WLED funktionieren auch, aber eine Reservierung lässt sich leichter im Blick behalten.
Home Assistant 2025.12.0 bis 2025.12.4 konnten eine MAC-Abweichung melden, obwohl die MAC gleich war, nur in anderer Groß- und Kleinschreibung. 2025.12.5 hat das behoben. Wenn Sie diesen Fehler sehen, aktualisieren Sie zuerst.
Szenen oder Szenenfolgen werden nicht angezeigt
- Neue Szenen erscheinen nicht im Select Preset. Vor Home Assistant 2025.11 wurde die Szenenliste einmal gelesen, für neue Szenen musste man die Integration also neu laden. Neuere Versionen aktualisieren sie, wenn das Licht meldet, dass sich seine Szenen geändert haben.
- Das Select Playlist ist nicht verfügbar. Es gibt keine Szenenfolgen auf dem Licht. Legen Sie eine in WLED an (siehe WLED-Szenenfolgen).
- Das Select zeigt "unknown", nachdem Sie das Licht geändert haben. Das ist WLED, nicht Home Assistant. Sobald Sie Farbe, Effekt oder Helligkeit ändern, ist das Licht nicht mehr "auf Szene 3", also meldet WLED keine aktive Szene, und Home Assistant zeigt unknown. Das ist so gewollt.
Um eine Szene in einer Automatisierung zu nutzen, rufen Sie select.select_option auf dem Select Preset mit dem Namen der Szene auf.
Segmente als Entitäten
Jedes WLED-Segment nach dem ersten wird in Home Assistant ein eigenes Licht, benannt "Segment 1", "Segment 2" und so weiter. Die Integration nutzt nicht die Segmentnamen, die Sie in WLED vergeben haben.
- Zu viele Entitäten? Deaktivieren Sie die Segment-Lichter, die Sie nicht nutzen.
- Entitäten hängen am falschen Segment, nachdem eines in der Mitte gelöscht wurde. Behoben in Home Assistant 2026.10. Auf älteren Versionen laden Sie die Integration nach Segmentänderungen neu.
- Keep Main Light. In den Optionen der Integration hält "Add 'Main' control even with single LED segment" das Main light dauerhaft vorhanden. Ist es an, steuern Segment-Lichter nur ihr eigenes Segment, und Ein/Aus und Gesamthelligkeit liegen auf dem Main light. Schalten Sie es ein, wenn Automatisierungen Segmente hinzufügen und entfernen.
WLED-Segmente erklärt behandelt, was Segmente auf der WLED-Seite sind.
Farben oder Weiß sehen aus Home Assistant falsch aus
Die Integration setzt nur die Primärfarbe des Segments. Vor 2026.10 konnte sie auf Streifen mit Warm- und Kaltweiß (RGB plus CCT) Farbe und Farbtemperatur nicht unabhängig voneinander setzen. Die WLED-Dokumentation merkt außerdem an, dass Home Assistant mit einer konfigurierten CCT-Einrichtung oder Weißabgleich-Korrektur nicht funktioniert, und empfiehlt, Calculate CCT from RGB in den LED-Einstellungen zu aktivieren. Home Assistant 2026.10 hat Sprünge im Farbrad und falsche Farbmodi auf RGB-plus-CCT-Streifen behoben, aktualisieren Sie also, bevor Sie Einstellungen ändern.
Firmware-Updates aus Home Assistant
Die Update-Entität bietet die stabilen WLED-Versionen an (und Betas, wenn Sie bereits eine Beta nutzen) und prüft alle paar Stunden auf neue. Was schiefgeht:
- Update scheitert auf WLED 16. WLED 16 hat eine Sicherheitsoption "Only allow update from same network/WiFi" (Config > Security & Updates). Ist Home Assistant in einem anderen Subnetz, verweigert das Licht das Update. Seit 2026.10 zeigt Home Assistant einen Fehler, statt stillschweigend zu scheitern. Schalten Sie die Option aus oder aktualisieren Sie aus demselben Netzwerk.
- Keine Update-Entität. Seit 2026.10 bekommt ein Licht, dessen Firmware-Quelle Home Assistant nicht erkennen kann (zum Beispiel eine selbst kompilierte Firmware), keine Update-Entität, und ein Update wird nur angeboten, wenn die Version eine Datei für Ihr Board hat.
- Die falsche Datei wurde installiert (zum Beispiel ein Ethernet-Board, das sein Ethernet verliert). Behoben in 2026.5, das die zu Ihrem Board passende Firmware-Variante wählt.
Zum manuellen Aktualisieren siehe WLED-OTA-Updates.
Home Assistant und andere Apps gleichzeitig
Die Integration hält eine WebSocket-Verbindung zum Licht offen und erhält Änderungen per Push. Seit Home Assistant 2026.6 fragt sie nicht mehr zusätzlich ab (Polling), solange diese Verbindung steht; davor fragte sie zusätzlich alle 10 Sekunden ab, was auf kleinen Boards Effekte stottern lassen konnte.
WLED begrenzt die WebSocket-Clients (die WLED-Dokumentation für Version 16 nennt 3 auf dem ESP8266 und 8 auf dem ESP32; verbindet sich einer mehr, wird der älteste getrennt). Home Assistant, jeder offene Tab der Weboberfläche und manche Handy-Apps belegen je einen. Bleiben die Live-Updates in einem davon aus, schließen Sie die Tabs der Weboberfläche, die Sie nicht brauchen. Ein ESP32 hat mehr Spielraum.
Wenn Sie Home Assistant nutzen, um Effekte an WLED zu streamen (LedFx oder ähnliche Apps), geht das Licht in den Echtzeitmodus und ignoriert alles andere. Siehe WLED hängt im Echtzeitmodus.
Stattdessen MQTT?
WLED spricht auch MQTT, aber die WLED-Dokumentation empfiehlt die native Integration, und MQTT-Autodiscovery für Home Assistant wird nicht unterstützt (WLED hat sie vor Jahren entfernt). Nutzen Sie MQTT nur mit gutem Grund, und richten Sie das Licht dann von Hand in YAML ein.
FAQ
Warum meldet Home Assistant bei WLED "Unknown error occurred"? Meist eine beschädigte Szenendatei auf dem Licht, manchmal Firmware älter als 0.14 oder ein Gerät, das nicht wie WLED antwortet. Home Assistant 2026.10 zeigt eine klarere Meldung.
Wie ändere ich die WLED-IP-Adresse in Home Assistant? Öffnen Sie den WLED-Integrationseintrag, wählen Sie Reconfigure und tippen Sie die neue Adresse ein. Legen Sie dann eine DHCP-Reservierung an, damit es nicht wieder passiert.
Warum ist mein WLED Main light nicht verfügbar? Das Licht hat nur ein Segment. Schalten Sie Keep Main Light in den Optionen der Integration ein, wenn Sie es immer haben möchten.
Kann Home Assistant WLED-Segmentnamen anzeigen? Nein, Segmente erscheinen als Segment 1, Segment 2 und so weiter. Benennen Sie die Entitäten in Home Assistant um.
Funktioniert es mit WLED 16? Ja. Home Assistant 2026.10 hat die bisher gemeldeten WLED-16-Probleme behoben, etwa stille Update-Fehler durch die Beschränkung auf dasselbe Netzwerk. Es hat auch das Durcheinander der Segment-Entitäten nach dem Löschen eines Segments in der Mitte behoben.