Fix Zigbee2MQTT Unavailable After Restart 2026

Fixing Zigbee2MQTT entities that show “unavailable” after restarting Home Assistant is one of the most common headaches in smart home automation. You reboot Home Assistant for a routine update, and suddenly every Zigbee sensor, switch, and light reports as unavailable — even though the devices are still paired and working fine inside Zigbee2MQTT’s own frontend.

I have dealt with this issue across multiple Home Assistant installations over the past few years, running everything from Home Assistant OS with the official add-on to Docker-based standalone setups. The good news is that the problem is well-understood, and there are five reliable fixes that cover every scenario I have encountered.

The short answer: Zigbee2MQTT entities become unavailable because Home Assistant starts listening for MQTT discovery messages before Zigbee2MQTT has finished sending them. Without the MQTT retain flag enabled, those missed messages are gone forever — leaving your entities stuck in an unavailable state until something triggers a resend.

This guide walks through the root cause in plain language, then gives you a quick diagnosis tool, five step-by-step fixes ranked from fastest workaround to permanent solution, and prevention tips so you never have to deal with this again.

Why Zigbee2MQTT Entities Show “Unavailable” After a Restart

The root cause comes down to a startup race condition between Home Assistant, the MQTT broker, and Zigbee2MQTT. Understanding this timing issue is the key to picking the right fix.

When Home Assistant restarts, it connects to your MQTT broker (typically Mosquitto) and begins listening on the discovery topic — usually homeassistant by default. Home Assistant learns about every Zigbee2MQTT device through MQTT discovery messages that Zigbee2MQTT publishes to this topic.

Here is where the problem starts. If Zigbee2MQTT has not finished initializing by the time Home Assistant connects to the broker, those discovery messages have already been published and missed. Home Assistant is now listening on an empty channel, waiting for announcements that already came and went.

Without the MQTT retain flag, there is no mechanism to replay those messages. The broker does not store them. Zigbee2MQTT does not know Home Assistant missed them. Your entities sit in an unavailable state indefinitely.

This is also why only some devices sometimes go unavailable. If Zigbee2MQTT is partially through its initialization when Home Assistant connects, you might catch some discovery messages but miss others. Battery-powered devices can be especially tricky because they may be sleeping and miss the polling cycle entirely.

One Reddit user described the frustration perfectly: “The only solution to get my devices available is to restart Zigbee2MQTT. Does someone have the same issue?” The answer is yes — hundreds of users across the Home Assistant community forums, GitHub issues, and Reddit threads report the exact same pattern.

Quick Diagnosis: Which Fix Do You Need?

Before applying any fix, take 30 seconds to identify your specific scenario. The right fix depends on your setup and how often the problem occurs.

Ask yourself these questions:

• Does it happen after every single Home Assistant restart? You need a permanent fix — skip to Fix 2 (retain flag) or Fix 4 (boot delay).
• Does it happen only occasionally or after updates? Start with Fix 1 (restart services) and then apply Fix 2 to prevent recurrence.
• Are devices showing as unavailable in Home Assistant but working fine in the Zigbee2MQTT frontend? This is the classic discovery timing issue — all five fixes apply.
• Are devices also unavailable inside Zigbee2MQTT itself? Your problem is in the Zigbee network, not MQTT. Check your coordinator connection and try re-pairing.
• Are you running Home Assistant Container or Core instead of Home Assistant OS? Pay special attention to Fix 4, since restart ordering behaves differently without the supervisor managing add-on startup.

For most users, the progression looks like this: apply Fix 1 to get your devices back immediately, then apply Fix 2 or Fix 4 to stop the problem from coming back.

Fix 1: Restart the MQTT Add-On and Zigbee2MQTT

This is the fastest workaround and the one most users discover on their own. It gets your devices back online within minutes, but it does not prevent the problem from recurring.

The key insight is the restart order. Many users restart Zigbee2MQTT first, which does not always work because Home Assistant has already given up listening for those discovery messages. The correct sequence is to restart the MQTT broker, then Zigbee2MQTT.

Step 1: Open Home Assistant and go to Settings, then Add-ons (or your Docker management interface if running standalone).

Step 2: Restart the Mosquitto MQTT broker add-on first. Wait for it to show as “started” in the logs.

Step 3: Restart the Zigbee2MQTT add-on. Watch the Zigbee2MQTT logs to confirm it connects to the broker and publishes discovery messages.

Step 4: Go back to your Home Assistant dashboard and check your Zigbee entities. They should now show their current states instead of “unavailable.”

If entities are still unavailable after this sequence, try restarting Home Assistant Core itself as a final step. As one GitHub issue contributor noted: “Restarting the Z2M add-on usually resolves the problem. Sometimes I have to reboot the host.”

This fix is reliable but temporary. As a Home Assistant Community user put it: “Workaround for me: restarting the MQTT add-on. I have to do this at least once a week.” If you find yourself doing this regularly, move on to the permanent fixes below.

Fix 2: Enable the MQTT Retain Flag (Permanent Fix)

This is the single most effective permanent fix. The MQTT retain flag tells the broker to store the last published message on each topic and replay it to any new subscriber — including Home Assistant when it reconnects after a restart.

With retain enabled, it does not matter whether Zigbee2MQTT finishes initializing before or after Home Assistant connects. The broker holds onto those discovery messages and delivers them the moment Home Assistant subscribes.

What the retain flag does: When Zigbee2MQTT publishes a discovery message with the retain flag set to true, the Mosquitto broker stores that message. When Home Assistant connects and subscribes to the discovery topic, the broker immediately sends all retained messages. Every entity gets rediscovered automatically.

Step 1: Open your Zigbee2MQTT configuration. If you are using the Home Assistant add-on, go to the Zigbee2MQTT add-on page and click the Configuration tab at the top.

Step 2: Navigate to the MQTT section of the configuration. Look for the setting labeled retain under the mqtt block.

Step 3: Set retain: true. In the YAML configuration, it looks like this:

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost:1883
  retain: true

Step 4: Save the configuration and restart the Zigbee2MQTT add-on. From now on, every discovery message Zigbee2MQTT publishes will be retained by the broker.

Step 5: Test the fix by restarting Home Assistant. Your Zigbee entities should come back online automatically within a minute or two, without any manual intervention.

One important note: enabling retain increases the storage the broker uses, but for a typical smart home with dozens of devices, the impact is negligible. The tradeoff is well worth it for automatic recovery.

If you are editing configuration.yaml directly (common for Docker or supervised installs), the same setting goes in your Zigbee2MQTT configuration file, not Home Assistant’s configuration.yaml. This is a common point of confusion for users new to the ecosystem.

Fix 3: Reconfigure the MQTT Integration in Home Assistant

If the retain flag is already enabled but entities are still unavailable, the MQTT integration in Home Assistant itself may need reconfiguration. This forces Home Assistant to drop and re-establish its connection to the broker, triggering a fresh round of discovery.

This fix is also useful when you have changed broker settings, switched from Mosquitto to another broker, or updated Home Assistant to a version that changed how MQTT integrations behave.

Step 1: In Home Assistant, go to Settings, then Devices and Services.

Step 2: Find the MQTT integration in the list and click on it.

Step 3: Click the Configure button. You will see options including “Re-configure MQTT broker.” Select this option.

Step 4: Enter your broker details if prompted. For the official Mosquitto add-on, the broker address is typically core-mosquitto and the port is 1883. For external brokers, use the appropriate IP and port.

Step 5: Save and confirm. Home Assistant will disconnect from the broker and reconnect, pulling in all retained discovery messages.

Step 6: Check your entities. If they were stuck due to a stale MQTT connection, they should now show their real states.

For users running Home Assistant Container, the MQTT integration is configured through your configuration.yaml file. If you need to force a reconnection, the simplest approach is to restart the Home Assistant container itself. The integration will re-read the broker settings and reconnect fresh.

A common pitfall: if your MQTT credentials have changed (for example, after a Mosquitto add-on update that reset the password), the reconfiguration step will fail silently. Check the Home Assistant logs for MQTT connection errors if entities remain unavailable after this fix.

Fix 4: Adjust Boot Delay and Restart Order

Even with the retain flag enabled, a proper startup sequence prevents edge cases where the broker is not yet ready when Zigbee2MQTT tries to connect. The boot_delay setting in Zigbee2MQTT gives the broker time to fully start before Zigbee2MQTT begins publishing.

This fix is especially important for Docker and supervised installations where the supervisor does not manage startup ordering as strictly as Home Assistant OS does with its add-ons.

Step 1: Open your Zigbee2MQTT configuration file or the add-on Configuration tab.

Step 2: Find the advanced section (or create it if it does not exist).

Step 3: Add or modify the boot_delay setting. A value of 30 seconds is a good starting point:

advanced:
  boot_delay: 30

Step 4: Save and restart Zigbee2MQTT. It will now wait 30 seconds after starting before connecting to the broker and beginning discovery.

Step 5: For the full restart chain to work, ensure your services start in this order: MQTT broker first, then Zigbee2MQTT (with boot delay), then Home Assistant.

In a Docker Compose setup, you can enforce this ordering using depends_on with health checks. Here is a simplified example:

services:
  mosquitto:
    image: eclipse-mosquitto
    restart: unless-stopped

  zigbee2mqtt:
    image: koenkk/zigbee2mqtt
    restart: unless-stopped
    depends_on:
      - mosquitto

  homeassistant:
    image: homeassistant/home-assistant
    restart: unless-stopped
    depends_on:
      - zigbee2mqtt

The depends_on directive ensures containers start in the right order. Combined with the boot_delay setting, this gives the broker and Zigbee2MQTT time to fully initialize before Home Assistant starts listening.

One user on the Home Assistant Community forums described the impact: “When Home Assistant is still starting up, the items are not yet available.” The boot delay directly addresses this timing gap by giving every service in the chain enough time to be ready.

Fix 5: Force Entity Re-Discovery (Last Resort)

If none of the above fixes bring your entities back, the nuclear option is to delete the affected entities from Home Assistant’s entity registry and let Zigbee2MQTT re-discover them from scratch. This is a last resort because it can break automations and dashboard cards that reference those entities by ID.

One Reddit user described this approach: “I’m thinking a fix would be to force remove all Zigbee2MQTT sensors and force HA to re-autodiscover them.” It works, but you should only use it when everything else has failed.

Step 1: Before deleting anything, note which entities are unavailable and what their entity IDs are. You will need this list to verify recovery and update any broken automations.

Step 2: In Home Assistant, go to Settings, then Devices and Services, then click the Entities tab.

Step 3: Filter by your Zigbee2MQTT devices. You can search for zigbee2mqtt or sensor.zigbee to find them quickly.

Step 4: Select the unavailable entities and click Remove. Home Assistant will warn you if any automations reference these entities — note those automations for later repair.

Step 5: Restart the Zigbee2MQTT add-on. As it initializes, it will publish fresh discovery messages for every device.

Step 6: Go back to the Entities tab and verify that your Zigbee devices have been rediscovered. They should appear with their correct states.

Step 7: If any entity IDs have changed (this can happen if Zigbee2MQTT assigns slightly different names), update your automations, scripts, and dashboard cards accordingly.

There is also a more targeted version of this fix. Instead of deleting entities one by one, you can temporarily disable MQTT discovery in Zigbee2MQTT, restart it, then re-enable discovery. This forces Zigbee2MQTT to republish all discovery messages without touching the entity registry:

# Temporarily set in Zigbee2MQTT configuration:
mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost:1883

homeassistant:
  discovery: false

Restart Zigbee2MQTT, wait 30 seconds, then set discovery: true again and restart once more. This republishes all discovery topics while preserving your existing entity registry entries.

Advanced Prevention Tips and Automated Recovery

Once you have applied the fixes above, there are several advanced strategies that can make your setup even more resilient. These are optional but worth considering if you want a truly hands-off smart home.

Switch from Mosquitto to EMQX

Several users report that switching from the Mosquitto MQTT broker to EMQX eliminates the unavailable entity problem entirely. One Reddit user shared: “I swapped Mosquitto with EMQX, now a reboot of Home Assistant always restores all entities and no entities become unavailable anymore.”

EMQX handles retained messages and session persistence differently than Mosquitto, which appears to make the startup race condition a non-issue. If you have tried the retain flag and boot delay fixes without full success, EMQX is worth testing. It runs as a Home Assistant add-on or as a standalone Docker container.

Enable the Zigbee2MQTT Availability Feature

Zigbee2MQTT has a built-in availability feature that periodically publishes device online/offline status. This is separate from the discovery timing issue, but it helps with overall reliability.

To enable it, add this to your Zigbee2MQTT configuration:

advanced:
  availability: true

With availability enabled, Zigbee2MQTT polls devices at regular intervals and publishes their actual status. Battery-powered devices get a longer polling interval to preserve battery life. This does not fix the startup discovery issue on its own, but it helps detect and report genuinely offline devices versus ones that are just missing discovery data.

Automate Recovery with a Home Assistant Script

If you want zero manual intervention, you can create a Home Assistant automation that detects unavailable Zigbee entities and triggers a recovery sequence automatically. Here is a basic template:

automation:
  - alias: "Auto-recover unavailable Zigbee entities"
    trigger:
      - platform: homeassistant
        event: start
    action:
      - delay:
          seconds: 60
      - service: mqtt.publish
        data:
          topic: zigbee2mqtt/bridge/request/backup
          payload: ""
      - delay:
          seconds: 30
      - service: homeassistant.update_entity

This automation waits 60 seconds after Home Assistant starts (giving services time to initialize), then publishes a request to Zigbee2MQTT and refreshes all entity states. Adjust the delays based on how long your setup takes to fully start.

For a more targeted approach, you can monitor specific entities and only trigger recovery when they go unavailable:

automation:
  - alias: "Restart Z2M if devices unavailable"
    trigger:
      - platform: state
        entity_id: sensor.your_zigbee_sensor
        to: "unavailable"
        for:
          minutes: 5
    action:
      - service: hassio.addon_restart
        data:
          addon: a0d7b954_zigbee2mqtt

This restarts the Zigbee2MQTT add-on automatically if a specific sensor stays unavailable for more than five minutes. Replace the entity ID and add-on slug with your own values.

Deployment-Specific Considerations

The fixes in this guide apply to all Home Assistant installation types, but there are some deployment-specific differences to keep in mind.

Home Assistant OS with add-ons: This is the most straightforward setup. The supervisor manages add-on startup ordering, and all configuration is done through the UI. Fixes 1 through 3 apply directly through the add-on Configuration tabs.

Home Assistant Container (Docker): You manage startup order yourself. Use Docker Compose with depends_on directives and the boot_delay setting together. The MQTT integration is configured in configuration.yaml rather than through the UI on first setup.

Home Assistant Core (venv): Similar to Container but running directly on the host. You will need to manage service dependencies through systemd, ensuring the MQTT broker starts before Zigbee2MQTT and Zigbee2MQTT starts before Home Assistant.

Home Assistant Supervised: A hybrid approach — you get add-on management but run on a full Debian system. Most fixes work like Home Assistant OS, but pay attention to system-level service ordering.

Regardless of your installation type, the retain flag fix (Fix 2) is the one that provides the most consistent improvement across all scenarios.

Frequently Asked Questions

Conclusion

Fixing Zigbee2MQTT entities that show “unavailable” after restarting Home Assistant comes down to understanding the MQTT discovery race condition and applying the right fix for your situation.

Start with Fix 1 (restart the MQTT broker then Zigbee2MQTT) for immediate recovery. Then apply Fix 2 (enable the retain flag) as your permanent solution — it is the single change that eliminates this problem for the majority of users. If you still see issues, add Fix 4 (boot delay) and consider Fix 3 (reconfigure MQTT integration) or Fix 5 (force re-discovery) for stubborn cases.

For users who want to go further, switching from Mosquitto to EMQX or setting up automated recovery scripts can make the problem disappear entirely. The key takeaway: this is a known, solvable issue, and you should never have to manually restart services after every Home Assistant reboot.