Zigbee2MQTT firmware updates without breaking things

Two completely different jobs get called a “Zigbee2MQTT firmware update,” and they break in different ways. One is updating the Zigbee2MQTT application itself, the add-on or container that talks to your coordinator. The other is pushing new firmware to a Zigbee device over the air. Confusing the two is how people end up re-pairing a mesh they never needed to touch. Here is how each one actually works, and what to do when one goes wrong.

Keep the whole data directory backed up, stay on the stable channel unless you have a reason not to, and read the release notes before an app update. For device firmware, do one device of a model first and accept that you probably cannot go back. When something looks wrong afterwards, re-interview the device and read the logs; re-pair only when a device is lost for good.

The two updates are not the same job

Updating the Zigbee2MQTT app swaps out the software on your server. It affects every device at once, it does not touch the radios inside your devices, and it is reversible: you can pin the previous version and restore your data directory.

Updating device firmware (OTA) rewrites the software inside one device. Zigbee2MQTT pulls those images from the Koenkk/zigbee-OTA repository and pushes them to a device you select. It is per-device, and it is close to one-way.

Neither one requires you to re-pair anything. That is worth saying plainly, because it is the most common piece of bad advice about Zigbee updates.

1. Know your coordinator before you update the app

If you are running a ConBee III or a RaspBee, one detail matters more than any other: Zigbee2MQTT’s coordinator backup and restore is implemented only for the zstack (Texas Instruments) and ember (Silicon Labs) adapters. ConBee and RaspBee are neither, so there is no coordinator_backup.json waiting for you if the stick dies. For those radios the backup path runs through deCONZ or Phoscon instead. Sort that out before an update day, not during one.

Also check the release notes for the version you are moving to. Breaking changes in Zigbee2MQTT are documented, and they usually take the form of a renamed entity or a removed attribute rather than anything that touches your radio. If you are still choosing a backend, Zigbee2MQTT vs ZHA: which to pick covers that decision.

2. Pick a channel: stable or Edge

The Home Assistant add-on repository ships exactly two variants, and it is worth knowing which one you installed:

• Zigbee2MQTT is the stable release. It tracks released versions and is the right choice for almost everyone.
• Zigbee2MQTT Edge tracks the dev branch. It exists for when you need a fix or a device definition that has not made it into a release yet.

On Docker the same split is the latest and latest-dev image tags. There is no separate beta channel to opt into. If you are running Edge on a network you depend on, that is the first thing to reconsider.

3. Back up the whole data directory

Everything Zigbee2MQTT knows about your network lives in its data directory, so back up the whole folder rather than picking files out of it:

• configuration.yaml, your settings, and the optional devices.yaml / groups.yaml split-outs if you use them
• database.db, the device database that holds your devices and their addresses
• state.json, the last known state of your devices
• coordinator_backup.json, the network backup, on zstack and ember adapters
• any external converters you have added

That coordinator_backup.json is the file that lets a replacement stick impersonate the old one so your devices rejoin on their own. My guide on how to survive a Zigbee coordinator failure covers pulling it out, putting it back, and the swap itself. A Home Assistant backup will capture the add-on’s data directory along with everything else, which is the easy route if you are on Home Assistant OS.

4. For device firmware, update one device of a model first

Device OTA updates run from the OTA tab in the Zigbee2MQTT frontend, and Home Assistant surfaces the same thing as an update entity. If you have eight of the same sensor, update one and live with it for a day before you do the other seven. That is where the real risk sits: a firmware image that misbehaves on your particular device, not a version number.

Two things to expect afterwards, both normal. Zigbee2MQTT re-interviews the device automatically, treating a freshly-updated device much like a newly-paired one to pick up new capabilities and re-configure it; you do not re-pair it yourself. One side effect is that this can reset custom reporting intervals back to defaults, so if you tuned a sensor’s reporting, check it afterwards. And the device reboots. Depending on its power-on behavior, a relay or bulb can switch on when it comes back, so do not run an OTA on the living room lights at 11pm, and think twice before updating anything driving a pump or a heater.

Testing “on a subset of devices” only makes sense here. An app update is all-or-nothing for the instance; you cannot roll it out to one Aqara Motion Sensor P1 and hold the rest back.

5. When something looks wrong afterwards

Work through it in this order, because the cheap fixes are also the most likely ones:

Read the logs first. Zigbee2MQTT’s log, and Home Assistant’s if the device is misreporting there. A renamed entity after an app update is a config problem, not a radio problem.

Re-interview or reconfigure the device. If a device reports the wrong values or is missing an entity after an update, this is the tool. It makes the device pull its configuration again without losing its identity on the network. In the frontend it is the Reconfigure option on the device page.

Roll the app back. Pin the previous version and restore the data directory you backed up in step 3. This is why the backup exists.

Downgrading device firmware is possible, but do not count on it. Zigbee2MQTT supports downgrade topics, and the default firmware source usually keeps the latest and one version back, so you generally get exactly one step of undo. Some devices reject older firmware outright. Treat a device OTA as effectively permanent and you will not be caught out.

What is not on this list is re-pairing. Re-pairing does not install firmware, it does not fix a version mismatch, and on a device like a SONOFF SNZB-04P contact sensor or a Philips Hue Smart Plug it mostly costs you the device’s history and its place in your automations. Re-pairing earns its place in two situations: a device that has dropped off the network and will not come back, and a coordinator swap you are doing without a network backup. It is the last resort, not the first response.

HomeKit and Hubitat notes

For HomeKit, Zigbee2MQTT devices reach Apple Home through Home Assistant’s HomeKit Bridge integration. An app update does not disturb that as long as your entity IDs survive, which they do unless you delete and re-pair devices.

For Hubitat, the hub has its own Zigbee radio, so Zigbee2MQTT is only in the picture if you are bridging a separate radio in over MQTT on purpose. Hubitat added built-in tooling to import Zigbee2MQTT devices in platform release 2.5.0 (April 2026), and a community Zigbee2MQTT Routing Driver has been around longer. Either way, check the driver side after a Zigbee2MQTT update that renames entities.