|

Smart Light Firmware Update Stuck Home Assistant Problems? What to Check First

ByAlex Turner

The most common reason a smart light firmware update gets stuck in Home Assistant is that the OTA (over-the-air) transfer hit a communication drop mid-way, leaving the light in a partial-update state. The light looks unresponsive, blinks in an unusual pattern, or stays on a single color. If you catch this early—before you restart Home Assistant or power‑cycle the bulb—you can often recover the light without re‑pairing.

Early Checkpoints: What to Look for Before You Touch Anything

Before you restart or remove the light, check these three signs. They narrow down whether the issue is a stalled transfer or a deeper coordinator problem.

  • Light behavior: Is the bulb flashing in a repeating pattern? A slow pulse (one flash every two seconds) usually means the OTA transfer is still active—wait another 10 minutes before acting. A rapid three-blink cycle every 2-3 seconds signals a failed update that needs a factory reset, not a power cycle. A solid unchanging color suggests the firmware hasn’t started.
  • Home Assistant status: Open the device in Settings > Devices & Services > Entities. If its `firmwareupdate` sensor shows `inprogress` for more than 15–20 minutes, the transfer has stalled. If the device shows `unavailable` and you didn’t remove it, the update likely broke the connection.
  • Coordinator log: In ZHA, check the Home Assistant Core log for messages like `OTA image page request failed` or `RETRIES_EXCEEDED`. In Zigbee2MQTT, open the frontend and look for `ota update` entries in the device log. A repeating `Failed to get image` line points to a broken OTA channel.

Branch to follow:

If the bulb is pulsing slowly (one flash per 2 seconds) and the `firmwareupdate` sensor shows `inprogress` with recent log entries, the transfer is still alive. Wait 10 minutes and check again. If instead the bulb is flashing rapidly (three quick blinks per second) and the log shows `RETRIES_EXCEEDED`, the update has irrevocably failed. In that case, do not power‑cycle the bulb—proceed directly to a factory reset (step 4 in Quick Fixes). Power‑cycling a bulb in that state can lock it into a corrupt recovery partition that refuses to accept new firmware.

Likely Causes of a Stuck Firmware Update

Three issues cause the majority of stuck updates. Ruling them out in order saves time.

Stale Coordinator Cache

Home Assistant’s OTA manager tries to resume an interrupted transfer by fetching the same firmware fragment from the device. If the coordinator’s cache has a stale checksum, the handshake fails repeatedly. This is most common with Zigbee2MQTT after a coordinator restart while an update was active.

Practical branch: If you see repeated `RETRIES_EXCEEDED` errors, try clearing the cache by restarting the Zigbee2MQTT add‑on only (not the entire Home Assistant instance), then retry the update. This preserves the OTA state but flushes the stale fragment cache.

Inconsistent Mesh Route

Firmware updates push large data packets over the mesh. A light that is two or three hops away from the coordinator—especially through a battery‑powered router—often loses packets. The update appears stuck because the transfer never reaches 100%. Check the network map in your coordinator’s frontend: if the light shows a route through a battery‑powered device, the update is likely to stall.

Common mistake: Don’t assume the light is connected directly. Open the map. If the route goes through a battery‑powered Zigbee router (like a motion sensor), the update will almost certainly fail. Move the light closer to a mains‑powered router or temporarily enable a nearby mains‑powered bulb.

Coordinator Firmware Overflow

Some coordinators (e.g., older ConBee II sticks) run out of memory when handling multiple OTA streams. If you started updates on two or three lights at nearly the same time, the coordinator may drop one stream. The “stuck” light is the one that lost its slot.

Check: In the coordinator log, look for `OTA slot unavailable` or `No free OTA session`. If present, stop all OTA updates, wait 60 seconds, and restart only one light’s update.

Quick Fixes to Try in Order

Work through these steps from least to most disruptive. After each step, verify the fix before moving to the next one.

Verification step: After any fix attempt, confirm the update succeeded by checking the device’s `firmware_update` sensor in Home Assistant. It should show `idle` or no update status. The light should respond to commands (on/off, brightness, color) within a few seconds. If the light still behaves erratically or the sensor shows `failed`, move to the next step.

1. Stop and restart the update from the coordinator frontend.

In Zigbee2MQTT, go to the device page and click Stop OTA, then wait 30 seconds and click Start OTA. In ZHA, remove and re‑add the device via the Devices list (this triggers a fresh OTA request). Do not restart Home Assistant yet—that kills the OTA process without cleanup.

2. Move the light closer to the coordinator (or a mains‑powered router).

If the light is a plug‑in bulb, bring it within 10 feet of the coordinator. For a hardwired light, turn on any nearby mains‑powered Zigbee lights to strengthen the mesh. Then initiate the update again.

3. Power‑cycle the light (only after step 1 or 2 have failed).

Flip the physical switch off for 15 seconds, then back on. The bulb will try to resume the firmware from its internal recovery partition. In many cases, it will re‑connect to Home Assistant and show the update as `failed`. You can then start a fresh update.

Failure mode to watch for: If the bulb re-pairs but the update still fails with the same `Failed to get image` error, the OTA file itself may be corrupted. Download the firmware image directly from the manufacturer and manually upload it via the coordinator tool (e.g., using Zigbee2MQTT’s `ota` command).

4. Factory reset the light and re‑pair.

This is the nuclear option. Consult the bulb’s manual for the reset sequence (typically a 5‑on/off pattern within a few seconds). After the reset, re‑pair and flash the latest firmware from scratch. This almost always works if the recovery bootloader is intact.

Recurrence pattern: A common trap: the update completes successfully, but after a few days the light drops off the network. This often points to a corrupted OTA file that passed verification but wrote bad data to a critical partition. Check the coordinator logs for `firmware image CRC mismatch`. If found, re‑flash with a freshly downloaded firmware file from the manufacturer’s website.

When to Stop and Investigate Further

If you have factory‑reset the light and the update still gets stuck (or the light never re‑pairs), the bulb’s non‑volatile memory may be corrupted. Before replacing it, check:

  • Is the coordinator firmware up to date? An outdated coordinator may not support the latest OTA protocol extensions. Update the stick’s firmware via the manufacturer tool.
  • Is the bulb model supported by your coordinator’s OTA provider? Not all Home Assistant OTA backends support every brand. For example, ZHA’s OTA provider only includes bulbs from IKEA, Philips, and a few others unless you add a custom provider. Check the device’s documentation on the Home Assistant forums.

Red flag: If the light blinks continuously for more than 60 seconds after a power‑cycle and never re‑connects, the recovery bootloader may be damaged. At that point, replacement is the only reliable fix.

Checklist: Smart Light Firmware Update Stuck Home Assistant

Use this quick decision aid before you start any step.

  • [ ] Does the light pulse slowly (once per 2 sec)? (Transfer still active – wait 10 minutes.)
  • [ ] Does the light flash rapidly (3 blinks per second)? (Update failed – go directly to factory reset, do not power‑cycle.)
  • [ ] Has the update been in `in_progress` for more than 20 minutes? (Stalled – stop and restart the OTA.)
  • [ ] Is the light more than two hops from the coordinator through a battery‑powered router? (Move it closer or enable a mains‑powered router.)
  • [ ] Did you start multiple OTA updates at once? (Stop all but one.)
  • [ ] After a fresh update attempt, does the log show `Failed to get image` repeatedly? (Try factory reset; if it fails again, check for corrupted OTA file.)

If you answered yes to any of these and a factory reset did not fix it, the bulb likely needs replacement.

Explore This Topic

Related guides in this cluster:

Similar Posts