If you’re thinking about changing your Zigbee2MQTT network key, you’re probably not setting up a fresh network. You have a coordinator, dozens of paired devices, groups and scenes already built, and something prompted the question: a default key you never changed, a secondhand coordinator you don’t trust, or two networks you need to converge onto one key.
The short version is that changing the key requires re-pairing every device, with no partial option. That cost is documented. Two things that follow are not, and both catch people out. Zigbee2MQTT will refuse to start immediately after your edit, with an error most guides never mention. And your groups and scenes won’t come back with your devices, even though Zigbee2MQTT’s own database will keep listing them.
What the network key actually protects
The Zigbee network key is the shared key that encrypts frames at the network layer across your whole mesh — every device on the network holds the same one. It sits below the application-support layer, which Zigbee secures separately with link keys, and it’s a different concern from permit_join, which controls whether new devices can join at all. Our permit_join security piece covers that side. This article is about the key protecting traffic on a network you’ve already built.
This is not a five-minute change on an established network. Every paired device needs re-pairing, one at a time, in most cases physically at the device. Copy coordinator_backup.json and database.db out of Zigbee2MQTT’s data directory before you touch anything, and block out real time — not just for the key change, but for the rebuild afterwards.
Why “change the default key” is fresh-install advice
Zigbee2MQTT’s securing the installation page lists changing the default network key alongside disabling permit_join after pairing and enabling the frontend’s auth_token. The advice is sound, and the project doesn’t hedge it: the network configuration reference says that if you’re running on the old default key, changing it is strongly suggested.
The default isn’t weak in a cryptographic sense; it’s published, and it’s identical across every installation that never changed it. Anyone within radio range who knows it can decrypt your mesh traffic.
advanced: # this exact array is Zigbee2MQTT's documented default key. # if your config contains it, you are on the published key. network_key: [1, 3, 5, 7, 9, 11, 13, 15, 0, 2, 4, 6, 8, 10, 12, 13] # option A: let Zigbee2MQTT generate one and write it back # network_key: GENERATE # option B: your own 16-value array, managed yourself
network_key takes either a 16-value array you supply, or the literal string GENERATE, which makes Zigbee2MQTT create a random key on its next startup and write the resulting array back into your config file in place of the word GENERATE.
What changing the key actually requires
There’s no incremental path. Both pages are direct: changing network_key requires re-pairing every device already on the network. The key change happens at the coordinator, and there’s no mechanism to push a new key to already-joined devices over the air, so each one has to rejoin to receive it.
Worth separating out, because migration threads blur the two: not every coordinator change forces this. Per the FAQ, if serial.adapter stays the same — zstack to zstack, ember to ember — re-pairing isn’t required. If it changes, the FAQ says re-pairing might not be needed, that results vary, and that the direction isn’t officially supported. A key change is its own trigger regardless of hardware. If you’re planning a coordinator swap rather than a rekey, our coordinator backup and restore guide covers that path properly.
| Change type | Re-pair required? |
|---|---|
| Same-adapter-family swap (zstack→zstack, ember→ember) | No |
| Cross-family migration (zstack↔ember) | Maybe — results vary, not officially supported |
| Network key change (array or GENERATE) | Yes, always |
Zigbee2MQTT won’t start after you change it
This is the step most write-ups skip, and it arrives before anything else. Edit network_key, restart, and Zigbee2MQTT stops with this:
Configuration is not consistent with adapter state/backup!
Nothing has gone wrong. Zigbee2MQTT’s fails to start page states that this error fires precisely when you edit pan_id, network_key or ext_pan_id — the coordinator is still running the old network, coordinator_backup.json still records it, and your config file now says something different. That file stores the network your coordinator actually holds: PAN ID, extended PAN ID, network key and channel. It’s the same file our channel-change guide tells you not to delete, for reasons that don’t apply here.
The docs give two ways out. Revert the values and carry on as before, or, if you meant it, remove coordinator_backup.json and restart — which re-commissions the network and requires re-pairing every device. For a key change, that second option isn’t a workaround. It is the procedure. Rename the file rather than deleting it, so reverting stays possible.
Removing coordinator_backup.json re-commissions your Zigbee network. Every device must be re-paired, and the file you remove is the one a coordinator restore reads from. Rename it, keep the copy you made, and only do this when a full re-pair is what you actually intend.
This also settles a question worth asking before you restore any older backup: because that file carries the network key, restoring one taken before a rekey puts the old key back. Back up after the change as well as before it.
GitHub issue #25220, “Doesn’t start after generating new network key,” is this error meeting someone who hadn’t found that page. The reporter set network_key: GENERATE and ext_pan_id: GENERATE together on an SLZB-06, restarted, and hit the wall — on Zigbee2MQTT 1.42.0, filed 15 December 2024. The genuinely useful detail in it is a recovery friction the docs don’t smooth over: the log prints the adapter’s stored values as strings, while configuration.yaml wants them as arrays, so reconciling the two by hand means converting formats. Note that setting one GENERATE rather than two changes nothing about the error. Any edit to those three values produces it.
The groups and scenes trap
Here’s the part the documentation genuinely doesn’t cover, and the reason this is worth planning rather than improvising.
Zigbee groups and scenes are not purely a Zigbee2MQTT database concept. Group membership and scene definitions live on the devices themselves. As our groups vs scenes guide puts it, Zigbee2MQTT broadcasts a group command and each member device decides for itself whether it belongs — there’s no central membership table being consulted. Scenes work the same way: the stored states live on the device.
So when a device re-pairs after a key change, it rejoins as a new device from the network’s perspective, and whatever was written to its onboard memory doesn’t come back with it. Zigbee2MQTT’s tracker documents both halves. Issue #28228 reports that a light re-entering pairing mode and rejoining is no longer part of its group. Issue #28706 reports the other side: Zigbee2MQTT doesn’t clear that membership from its own data structures when a device re-joins.
Together that produces the confusing bit. Your dashboard still shows a “Living Room Evening” scene and a light group with every member correctly listed, and none of it does anything, because the devices no longer know they belong.
Groups and scenes are stored on the devices as well as in Zigbee2MQTT’s database. A full re-pair wipes the on-device side while the database entries survive, so they look intact and stop working. There is no known way to preserve them through a re-pair — the approach below rebuilds them, it doesn’t save them.
Rebuilding: one documented account
The closest thing to a real-world account comes from a Home Assistant Community thread opened in May 2026, where the original poster lost all groups and scenes on a 121-device network after a key change and full re-pair, then documented a manual rebuild: record every group membership and scene name first, change the key and re-pair, then re-add devices to groups and re-save scenes from Home Assistant.
They put the whole job at roughly six hours across about 120 devices, with the rebuild going faster than the re-pairing. That’s one self-reported figure from one large network on a thread that was never marked solved — a sense of scale, not a benchmark.
The sequencing holds regardless of timing, though, and it’s the part worth copying: inventory groups and scenes before you touch the key, don’t rely on the database to remind you afterwards, and expect the rebuild as a separate pass once re-pairing is finished.
When this is actually worth doing
Given the cost — a full re-pair, a rebuild, and a network re-commission in between — it’s worth being honest about when this earns its disruption.
It clearly does if you’re still on the published default key, which is the case the project itself calls out. It does if you bought a secondhand coordinator and don’t know what key it holds, if you have specific reason to think your key was exposed, or if you’re merging two networks onto one key.
The weaker case is a large, stable network already running a unique key, where the motivation is tidiness rather than a threat. Rekeying doesn’t improve much there, and it costs a mesh. If what’s really bothering you is exposure on the network side rather than the mesh side, the Mosquitto broker security checklist likely addresses more actual risk for far less disruption.
FAQ
Does changing the Zigbee2MQTT network key require re-pairing all my devices?
Yes. The configuration reference and the FAQ both state it directly, with no partial or over-the-air option. Every device rejoins individually.
Why won’t Zigbee2MQTT start after I changed the network key?
Because coordinator_backup.json still describes the old network. Zigbee2MQTT logs “Configuration is not consistent with adapter state/backup!” whenever pan_id, network_key or ext_pan_id in your config disagree with the adapter’s stored state. Revert the change, or remove that file and restart to re-commission — which means re-pairing everything.
Will changing the network key delete my Zigbee2MQTT groups and scenes?
Effectively, yes. Group memberships and scene definitions stored on-device are lost when devices re-pair, while Zigbee2MQTT’s database keeps listing them non-functionally. Both behaviours are reported on the project’s tracker. There’s a manual rebuild, not a preservation method.
How do I generate a new random Zigbee2MQTT network key?
Set network_key: GENERATE under advanced in configuration.yaml. Zigbee2MQTT generates a key on its next startup and writes the array back into the file. Expect the consistency error on that same startup, and handle the coordinator backup as above.
Does changing the network key also change my Zigbee channel or PAN ID?
No — they’re separate settings. But they’re checked together against the coordinator backup, so editing any of them triggers the same startup error and the same re-commission decision.
What this research verified
The mechanics come from Zigbee2MQTT’s own documentation: that network_key accepts an array or GENERATE, that changing it requires re-pairing every device, that the default array is published and should be changed, and that the “Configuration is not consistent with adapter state/backup!” error is caused by editing pan_id, network_key or ext_pan_id and resolved by reverting or removing the coordinator backup. The same-adapter and cross-adapter re-pairing rules come from the FAQ, including its caveat that the cross-family direction isn’t officially supported.
The groups and scenes mechanism is supported by two issues on Zigbee2MQTT’s tracker (#28228, #28706) and is consistent with the per-device membership model in our own groups vs scenes coverage. The rebuild account and the six-hour figure come from a single unresolved community thread and are one person’s report, not a verified benchmark. Issue #25220’s details — Zigbee2MQTT 1.42.0, SLZB-06, filed 15 December 2024 — are as reported on the issue; its current state may have moved since.
This is a research-synthesis piece. Nothing here was tested on this site’s own network, and there’s no test-bench data behind any claim above. The whole mechanism is local: the key, the re-pairing and the rebuild all happen on your own coordinator and broker, with no cloud dependency at any point. Before you start, check your own Zigbee2MQTT version’s network configuration page, confirm where your data directory is, and get a copy of coordinator_backup.json and database.db somewhere the data directory’s own failures can’t reach.