Zigbee2MQTT documents coordinator backup and restore across three pages that don’t reference each other: the FAQ answers “how do I migrate adapters” in a few terse lines, the MQTT topics reference describes the backup request, and the IEEE-address step sits on a flashing page. This guide assembles them: how to create a backup, what’s in it, which adapters support it at all, and what a restore does and doesn’t get you back.
This is a mechanism explainer, not a specific-device walkthrough. If you’re choosing coordinator hardware rather than protecting one you already run, the ZBDongle-E vs ZBDongle-P, SkyConnect/ZBT-1 and SLZB-06 guides cover that decision. This page assumes you already have a coordinator and want to keep the network it’s holding together.
What’s actually in a Zigbee2MQTT backup
A Zigbee2MQTT backup isn’t a single database export. It’s the data folder, and four files in it carry the weight:
configuration.yaml # settings, MQTT broker config, device/group list
coordinator_backup.json # coordinator network data: what lets a
# replacement adapter rejoin without re-pairing
database.db # internal device IDs and network addresses
state.json # last-known device states (can be stale)
Of the four, coordinator_backup.json is the one that matters for hardware recovery — it’s the network data a replacement adapter needs to pick up where the old one left off. The other three matter for a full instance restore (reinstalling Home Assistant/OS, moving to new storage) but aren’t what saves you from re-pairing 50 devices after a coordinator dies.
Worth knowing before you go looking for a button: Zigbee2MQTT writes coordinator_backup.json into its data directory by itself, which is what makes the automatic restore below possible at all. If your coordinator just died and you never once triggered a backup, look in that directory anyway. What a manual backup adds is a copy somewhere the data directory’s own failures can’t reach.
This backup lives entirely inside Zigbee2MQTT’s own data folder. Home Assistant’s automations, scripts and entity registry are a separate system with their own backup path. Restoring here gets your Zigbee network back and nothing else.
How to trigger a backup
Two supported methods, both documented, neither requiring you to shut anything down first.
Frontend. Since Zigbee2MQTT 1.26.0 there’s a “Download data folder backup” button, under Settings → Tools on current builds — the frontend has rearranged itself before, so trust your own install over any screenshot. It packages the data folder as a zip your browser downloads, which is the fastest way to get a copy off the machine.
MQTT. Publish an empty message to zigbee2mqtt/bridge/request/backup. This is the part that trips people up: the backup does not appear as a new file in the data folder. Zigbee2MQTT replies on zigbee2mqtt/bridge/response/backup with the zip base64-encoded inside the JSON payload, so a publish on its own accomplishes nothing — you have to be listening for the response and decode it.
// terminal 1: wait for the response, decode it, write the zip mosquitto_sub -h 192.168.10.20 -C 1 \ -t 'zigbee2mqtt/bridge/response/backup' \ | jq -r '.data.zip' | base64 -d > z2m-backup.zip // terminal 2: ask for the backup mosquitto_pub -h 192.168.10.20 \ -t 'zigbee2mqtt/bridge/request/backup' -m ''
The payoff for that extra step is that it scripts: run it from whatever already backs up the rest of your home-automation host and a copy lands off-box on a schedule instead of only when you remember.
The hard limit: only zstack and Ember adapters
The FAQ states this plainly, and it’s the line that decides whether the rest of this article applies to you: backup and restore is implemented only for the zstack (Texas Instruments) and ember (Silicon Labs) adapter types. It is explicitly not implemented for conbee, ezsp, zboss, or zigate. Whether you’re covered is decided by the serial.adapter value in your configuration.yaml, not by the brand on the stick.
| Adapter type | Backup/restore support | Example hardware |
|---|---|---|
| zstack | Supported | Sonoff ZBDongle-P and other TI-chipset sticks |
| ember | Supported | SkyConnect/ZBT-1, SMLIGHT SLZB-06 in Ember mode |
| conbee / deconz | Not supported | ConBee II/III, RaspBee |
| ezsp | Not supported | Silicon Labs adapters left on older EmberZNet firmware |
| zboss | Not supported | — |
| zigate | Not supported | ZiGate |
ConBee/RaspBee (deconz) adapters can’t create a Zigbee2MQTT backup at all. This isn’t a restore limitation — there is nothing to restore from. If you plan to migrate off ConBee hardware, budget for a full re-pair, or look at a third-party tool such as zigpy-cli, which is a community workaround outside Zigbee2MQTT’s backup system.
The ezsp row is the one worth a second look, because it isn’t a hardware verdict. ezsp is Zigbee2MQTT’s deprecated Silicon Labs driver, kept for adapters on EmberZNet firmware older than 7.4.x; ember is the current driver for the same chips. A SkyConnect/ZBT-1 or ZBDongle-E sitting on ezsp is a firmware update and a config line away from being backup-capable.
Restoring after a coordinator dies (same adapter family)
If a zstack or ember coordinator fails and you replace it with the same adapter type, there’s no restore button and no restore MQTT command. Zigbee2MQTT does it on startup: it sees a blank adapter, factory-fresh or newly flashed, and writes the network back onto it from coordinator_backup.json. A maintainer confirmed that startup-triggered behavior in discussion #8112.
What comes across is the whole network identity: PAN ID, network key, routing table, and the old coordinator’s IEEE address. That last one matters more than it looks, because your devices hold bindings and reporting configuration pointing at the coordinator by its IEEE address. A network restored onto an adapter still announcing its own factory address is a network where a lot of things nearly work. Zigbee2MQTT keeps a dedicated page on copying an adapter’s IEEE address — and note that it lives under flashing, not configuration. There’s no IEEE field in configuration.yaml for you to fill in. The address is written to the adapter itself, by the restore or by the vendor’s flashing tool.
On EFR32 (ember) adapters the custom IEEE address is stored in a manufacturing token that can only be written once and cannot be changed afterwards. Confirm the old coordinator’s address before anything writes to the new stick, and after the swap check that Zigbee2MQTT reports that address rather than the replacement’s factory one. Community migration reports describe the write failing quietly on some chips, leaving the adapter announcing its factory address as though the step had worked.
Migrating to a different (but still backup-compatible) adapter
Here the FAQ is more specific than most guides repeat, and the distinction is worth having before you buy anything. If serial.adapter stays the same — zstack to zstack, ember to ember — re-pairing is not required. If it changes, zstack to ember or ember to zstack, the FAQ says re-pairing might not be required, that results vary, and that this direction is not officially supported.
That cuts straight through the most common upgrade path in this cluster: a Sonoff ZBDongle-P is a TI chip on zstack and a ZBDongle-E is a Silicon Labs chip on ember, so swapping one for the other in either direction is the cross-driver case, not the easy one. Plan it as a maintenance window with a full re-pair as the fallback. The other way to land in a re-pair is starting the new adapter already provisioned with a network of its own, so flash it blank first.
Migrating away from an adapter that can’t back up at all (ConBee, ZiGate, zboss, or a Silicon Labs stick you can’t move off ezsp) is a different, harder project. Those adapters can’t produce a coordinator_backup.json in the first place, so there’s no automatic restore path onto the new hardware, and the practical outcome is re-pairing everything on the new coordinator.
What restore does not give you back
A few gaps worth knowing before you rely on backup as a safety net:
- No on-demand restore onto an already-provisioned adapter. Restore-on-startup applies to a blank adapter. A user in that same discussion asking how to re-trigger one against a running, already-paired coordinator found no supported path.
state.jsoncan be stale. It captures last-known device states, not a live snapshot, so a restore may show devices in whatever state they were in at backup time rather than their actual current state.
There’s also a failure mode that looks like a restore problem and isn’t. If the network settings in configuration.yaml disagree with what the adapter and the backup say, Zigbee2MQTT logs Configuration is not consistent with adapter state/backup! at startup and names the parameter it objected to. The escape hatch that error offers is removing coordinator_backup.json, which re-commissions the network and re-pairs everything — the opposite of a restore. If a thread tells you to delete that file, rename it instead. Our channel-change guide covers that trap in full.
A dead coordinator, which is this article, is not the same failure as a corrupted database on a working adapter. Zigbee2MQTT keeps a rolling database.db.backup for that one: see the database.db corruption guide.
When to back up
Take a copy off the machine before anything that touches the coordinator or its data folder: a coordinator firmware update, a channel change, a Home Assistant or OS reinstall, a move to different storage. On a schedule is better still, because the failures that take out a data directory — a filling disk, a dropped network mount — don’t announce themselves in advance, and coordinator_backup.json sits in that same directory as database.db.
My own view, and it’s a view rather than a finding: the least reversible step in this entire procedure, the one-time IEEE write, is documented on a flashing page rather than alongside the migration answer most people start from. Read that page before you order the replacement adapter, not after it arrives.
FAQ
Does a Zigbee2MQTT backup include my Home Assistant automations?
No. It covers Zigbee2MQTT’s data folder only. Home Assistant automations, scripts and the entity registry are a separate system with their own backup process.
Can I restore a Zigbee2MQTT backup onto a different brand of coordinator, like moving from ConBee to a Sonoff dongle?
No. Backup and restore is implemented only for zstack and ember adapters, and ConBee/deconz can’t produce a backup at all, so there’s nothing to carry over. A ConBee-to-Sonoff move means re-pairing every device.
What’s the difference between coordinator_backup.json and the full data-folder backup?
coordinator_backup.json is the coordinator’s network data — what lets a replacement zstack or ember adapter rejoin without re-pairing. The full data-folder backup bundles it with configuration.yaml, database.db and state.json, which is what you want for a complete instance restore.
Will restoring a backup change my device IDs or break Home Assistant automations?
A successful restore is built to avoid it. Devices keep their own IEEE addresses, database.db carries their records and friendly names across, and Home Assistant’s MQTT entities follow those names, so entity IDs stay put. That follows from what the restore carries rather than from a documented statement about automations, so treat it as the expected outcome rather than a guarantee. What does break automations is the branch where the restore doesn’t happen: re-pair onto a fresh network without the device database, and devices come back under default names with new entity IDs behind them. That’s the reason to back up database.db alongside coordinator_backup.json.
What this article verified
This is a research-synthesis explainer, not a bench-tested walkthrough. No backup or restore cycle was run on this site’s test bench for it, and the MQTT example above is representative rather than captured output.
Traceable directly to Zigbee2MQTT’s own documentation: the zstack-and-ember-only limitation, the same-driver no-re-pair case, and the caveat that a cross-driver move between zstack and ember is not officially supported and gives varying results (FAQ); the backup request and the base64-encoded zip returned on bridge/response/backup (MQTT topics reference); the one-time custom IEEE write on EFR32 adapters (the IEEE-copying page). The frontend button arriving in 1.26.0 and the four named files come from a 1.26.0 changelog writeup. The automatic restore against a blank adapter, and the absence of any way to force one onto an already-provisioned adapter, come from discussion #8112, including a maintainer’s confirmation. Reports of the IEEE write failing quietly are community migration threads, not documented behaviour.
Before your own migration: confirm the serial.adapter value in configuration.yaml, get a fresh copy of coordinator_backup.json and database.db off the machine, and check afterwards that Zigbee2MQTT reports the IEEE address you expect rather than the new adapter’s factory one.