WLED and Home Assistant: Common Problems and Fixes

Home Assistant has a built-in WLED integration, and usually it works without fuss: it finds the light, creates a light entity and a handful of controls, and stays in sync. When it doesn’t, the cause is usually one of a few things, and several of them were fixed in recent Home Assistant releases. So the first question is always: which Home Assistant version are you on? This page notes the release that changed each behavior.

Setting up the integration from scratch is covered well in the official docs. This page is about what goes wrong.

What the integration creates

Knowing what to expect makes “missing” entities easier to spot. For each WLED light you get:

Entity	What it is
Light	The light itself, with color, brightness and an effect list. With more than one segment, one light per segment
Main light	Only with more than one segment (or with Keep Main Light on): power and overall brightness for the whole device
Preset and Playlist selects	Load a preset or start a playlist
Color palette select	Per segment, under configuration
Live override select	Off, On, or Until device restarts (the same as WLED’s live data override)
Speed and Intensity numbers	Per segment, the effect sliders
Switches	Nightlight, Sync send, Sync receive, and per segment Reverse and Freeze
Sensors	Estimated current, Max current, LED count, IP. Uptime, free memory and the Wi-Fi sensors exist but are disabled by default
Restart button and firmware update	Under configuration and diagnostics

The integration needs WLED 0.14.0 or newer. On older firmware setup fails. Since Home Assistant 2025.12 it says so plainly; before that it showed a generic error.

WLED not discovered by Home Assistant

Home Assistant finds WLED through mDNS (zeroconf, the _wled._tcp service). Nothing shows up in Discovered when:

• The light and Home Assistant are on different VLANs or subnets. mDNS doesn’t cross subnets unless your router or a reflector forwards it. This is the most common reason on networks with a separate IoT VLAN.
• WLED’s mDNS name is empty. In Config›WiFi & Network (WiFi Setup before WLED 16), the mDNS address field must have a name (the default looks like wled-abcdef). Empty means no mDNS at all.
• Your access point isolates Wi-Fi clients (often called client or AP isolation, common on guest networks).
• Home Assistant’s own network settings exclude the interface the light is on.

You don’t need discovery. Add the integration by hand: Settings›Devices & services›Add integration›WLED and type the light’s IP address. Recent versions also accept a pasted URL and keep just the host.

If you don’t know the IP: the WLED web UI shows it in Info, your router lists it, and in WLED Max it’s in the Device Info section of a light’s settings, as IP Address.

“Unknown error occurred” when adding WLED

Up to Home Assistant 2026.9, the setup only recognized two problems: “can’t connect” and (from 2025.12) “firmware too old”. Anything else ended as Unknown error occurred. In practice “anything else” was:

• A damaged presets file on the light. The integration reads the light’s presets during setup, and invalid JSON in presets.json made it fail. This is the cause in most reports. Back up what you can and fix the presets; see WLED presets not saving or error 12 and backing up WLED. People who did a factory reset fixed it for the same reason: the reset wipes the bad file.
• Something at that address that isn’t WLED, or a WLED that answers with an error page, for example while it’s busy rebooting.
• Firmware older than 0.14 on Home Assistant releases before 2025.12.

Home Assistant 2026.10 replaces the vague message with “The device didn’t respond like a WLED device”, which points you at the same causes.

WLED entities unavailable

“Unavailable” means different things depending on which entity it is:

• Everything unavailable. Home Assistant can’t reach the light. Check that it’s online (open its web UI) and that its IP hasn’t changed (next section).
• The Main light only. The light has a single segment now. The Main light only exists while there are two or more segments, and it stays in the entity list as unavailable when you go back to one. Turn on Keep Main Light if you add and remove segments often (below).
• Segment lights, segment speed, palette, reverse or freeze. That segment no longer exists. Home Assistant never deletes segment entities on its own; remove leftover ones by hand.
• Preset or Playlist select. The light has no presets, or no playlists. Save one and it appears.

On ESP8266 lights with many effects and palettes, the whole device used to drop to unavailable now and then because the light’s big /json answer got cut off. Home Assistant 2026.10 reads effects and palettes separately and fixed that, along with “a broken presets file no longer makes the whole device unavailable”.

WLED changed IP address

DHCP can hand the light a new address after a router restart or a long power cut. What happens next depends on your version:

• If discovery works, Home Assistant notices the new address and updates it by itself. Since 2026.10 it first checks that the device at the new address has the same MAC address, which also stopped a bug where a manually fixed address was reverted half an hour later.
• If discovery can’t see the light (different VLAN), use Reconfigure on the WLED integration entry and type the new IP. It refuses if the MAC doesn’t match (“MAC address does not match”), which is a safety check, not a fault.

The lasting fix is a DHCP reservation for every WLED light in your router. Static IPs in WLED’s WiFi settings work too, but a reservation is easier to keep track of.

Presets or playlists not showing

• New presets don’t appear in the select. Before Home Assistant 2025.11 the preset list was read once, so new presets needed an integration reload. Newer versions update it when the light reports that its presets changed.
• The Playlist select is unavailable. There are no playlists on the light. Create one in WLED (see WLED playlists).
• The select shows “unknown” after you change the light. That’s WLED, not Home Assistant. As soon as you change color, effect or brightness, the light is no longer “on preset 3”, so WLED reports no active preset and Home Assistant shows unknown. It’s expected.

To use a preset in an automation, call select.select_option on the preset select with the preset’s name.

Segments as entities

Each WLED segment beyond the first becomes its own light in Home Assistant, named “Segment 1”, “Segment 2” and so on. The integration doesn’t use the segment names you gave in WLED.

• Too many entities? Disable the segment lights you don’t use.
• Entities attached to the wrong segment after deleting one in the middle. Fixed in Home Assistant 2026.10. On older versions, reload the integration after changing segments.
• Keep Main Light. In the integration’s options, “Add ‘Main’ control even with single LED segment” keeps the Main light around all the time. With it on, segment lights only control their own segment, and power and overall brightness live on the Main light. Turn it on if automations add and remove segments.

WLED segments explained covers what segments are on the WLED side.

Colors or white look wrong from Home Assistant

The integration sets the segment’s primary color only. Before 2026.10 it couldn’t set color and color temperature independently on strips with warm and cold white (RGB plus CCT). WLED’s own docs also note that Home Assistant doesn’t work with a configured CCT setup or white balance correction, and suggest enabling Calculate CCT from RGB in the LED settings. Home Assistant 2026.10 fixed color wheel jumps and wrong color modes on RGB plus CCT strips, so update before changing settings.

Firmware updates from Home Assistant

The update entity offers WLED’s stable releases (and betas if you already run a beta), and checks for new ones every few hours. Things that go wrong:

• Update fails on WLED 16. WLED 16 has a security option “Only allow update from same network/WiFi” (Config > Security & Updates). If Home Assistant is on a different subnet, the light refuses. Since 2026.10 Home Assistant shows an error instead of failing quietly. Turn the option off or update from the same network.
• No update entity. Since 2026.10 a light whose firmware source Home Assistant can’t identify (a self-built build, for example) gets no update entity, and an update is only offered when the release has a file for your board.
• The wrong file got installed (for example an Ethernet board losing Ethernet). Fixed in 2026.5, which picks the build that matches your board.

For updating by hand, see WLED OTA updates.

Home Assistant and other apps at the same time

The integration keeps a WebSocket connection open to the light and gets changes pushed. Since Home Assistant 2026.6 it stops polling while that connection is up; before that it also polled every 10 seconds, which could make effects stutter on small boards.

WLED limits WebSocket clients (WLED’s docs for version 16 give 3 on ESP8266 and 8 on ESP32; when one more connects, the oldest is dropped). Home Assistant, every open web UI tab and some phone apps each take one. If live updates stop in one of them, close the web UI tabs you don’t need. An ESP32 has more room.

If you use Home Assistant to stream effects to WLED (LedFx or similar apps), the light goes into realtime mode and ignores everything else. See WLED stuck in realtime mode.

MQTT instead?

WLED also speaks MQTT, but WLED’s docs recommend the native integration, and MQTT autodiscovery for Home Assistant isn’t supported (WLED removed it years ago). Use MQTT only if you have a reason, and then set up the light by hand in YAML.

FAQ

Why does Home Assistant say “Unknown error occurred” for WLED? Most often a damaged presets file on the light, sometimes firmware older than 0.14 or a device that isn’t answering like WLED. Home Assistant 2026.10 shows a clearer message.

How do I change the WLED IP address in Home Assistant? Open the WLED integration entry, choose Reconfigure and type the new address. Then set a DHCP reservation so it doesn’t happen again.

Why is my WLED main light unavailable? The light has only one segment. Turn on Keep Main Light in the integration options if you want it always.

Can Home Assistant show WLED segment names? No, segments appear as Segment 1, Segment 2 and so on. Rename the entities in Home Assistant.

Does it work with WLED 16? Yes. Home Assistant 2026.10 fixed the WLED 16 problems reported so far, such as silent update failures with the same-network lock. It also fixed segment entities mixing up after a segment in the middle is deleted.