Main

Replacing a Zigbee Coordinator Without Re-Pairing Forty Devices: A Pre-Flight Decision Procedure

October 10, 2026

The phrase “network-key migration” is the wrong mental model for a coordinator swap, and it leads people to look for a step that does not exist in the documented workflow. The network key is not the thing you carry across to a new stick. It is one of the things that, if you change it, forces a full re-pair. What actually determines whether forty devices need re-pairing is the adapter family on both ends and whether Zigbee2MQTT’s backup and restore path is implemented for them.

This article is a pre-flight decision procedure for Home Assistant operators running Zigbee2MQTT. It is not a promise that your swap will be clean. The documentation is explicit about which cases are supported, which are unofficial, and which require re-pairing. Read that first, then decide whether to unplug anything.

What the network key is, and what it is not

Zigbee devices are limited to one coordinator and one network. Moving a device to a different network requires a factory reset and re-pair. That is a protocol-level constraint, not a Zigbee2MQTT quirk. The Zigbee2MQTT FAQ states it plainly: “Any Zigbee device is limited to only be paired/joined to one Zigbee Coordinator and only be part of one Zigbee network… If you want to move a Zigbee device to a different Zigbee network then you need to factory reset that Zigbee device and re-pair/re-join it to the other Zigbee Gateway.”

The network key is part of what defines that network. Changing network_key or pan_id in configuration.yaml is listed under operations that require re-pairing all devices. Changing the Zigbee channel might require re-pairing some devices. So the key is not a portable credential you hand to a new coordinator to keep the old network alive. It is one of the parameters whose change breaks the old network.

What a coordinator swap actually moves is the coordinator’s own state: its IEEE address, its backup, and the device database under data/. Whether that is enough depends on the adapter family.

The three migration classes

The Zigbee2MQTT FAQ groups adapter migrations into three practical cases. The class you are in decides whether you plan for a re-pair or attempt a no-re-pair swap.

Class A: same adapter family, backup/restore supported

Backup and restore support is implemented only for zstack (Texas Instruments) and ember adapters. It is not supported for conbee, ezsp, zboss, or zigate.

Within that supported set, the FAQ says: “When the serial.adapter in the configuration.yaml is zstack or ember and the serial.adapter stays the same; e.g. zstack -> zstack re-pairing is not required.”

This is the case where a coordinator swap can preserve pairings. It is also the case where the network key is irrelevant to the procedure, because you are not changing it.

Class B: cross-family zstack <-> ember

The FAQ says: “When switching from zstack -> ember or ember -> zstack re-pairing might not be required, however results might vary as this is not officially supported.”

That sentence contains two different claims. “Might not be required” is the optimistic half. “Not officially supported” and “results might vary” are the operative half. Plan for a re-pair, attempt the no-re-pair path, and verify device by device. Do not schedule this on a Sunday evening when the household expects lights to work.

Class C: unsupported adapter families

If either end is conbee, ezsp, zboss, or zigate, backup and restore is not supported. The FAQ notes that “you might have success using this method,” referring to an unofficial approach, but it does not offer a supported no-re-pair path for these adapters. Treat the swap as a re-pair event and budget the time accordingly.

The exception that catches people who reason by family name

There is one documented exception inside the zstack family: “when switching from a CC2531 or CC2530 (Z-Stack 1.2) to a CC2652/CC1352 (Z-Stack 3) re-pairing is required.”

Both ends are zstack. The family label alone would suggest Class A. The Z-Stack generation is what matters, and the FAQ treats the 1.2 to 3 jump as a re-pair. If you are retiring a CC2531, do not assume the same-family rule applies.

Pre-flight card

Fill this in before ordering hardware or unplugging anything. The answers determine which procedure you follow.

  • Current serial.adapter value. Read it from configuration.yaml. Allowed values are zstack, ember, deconz, zigate, or zboss. If you rely on mDNS autodetection, note that the adapter and baudrate parameters in configuration.yaml are ignored when autodetection is used, so the value in the file may not reflect what is actually running.
  • Target adapter family. Same value as above, or different.
  • Backup/restore implemented on both ends? Yes only if both are zstack or both are ember. No for conbee, ezsp, zboss, zigate, or any cross-family combination.
  • Z-Stack generation, if applicable. CC2531/CC2530 is Z-Stack 1.2. CC2652/CC1352 is Z-Stack 3. A jump between them is a re-pair even though both are zstack.
  • Is data/ intact and backed up? Details about your network are stored in both the coordinator and the files under data/. If running as a Home Assistant add-on, data/ is renamed zigbee2mqtt/. Copy the contents before you touch hardware.

One more constraint worth stating: each Zigbee2MQTT instance supports a single dedicated coordinator, and that coordinator cannot already be in use by another application. Do not run the old and new sticks against the same instance at the same time.

The procedure

The FAQ gives the order. Follow it rather than improvising.

  1. Make sure you are running the latest version of Zigbee2MQTT.
  2. Stop Zigbee2MQTT.
  3. Decide whether re-pairing is required, using the pre-flight card above.
  4. If re-pairing is required: remove data/coordinator_backup.json (if it exists) and data/database.db. Under the Home Assistant add-on, data/ is zigbee2mqtt/.
  5. If re-pairing is not required: copy the IEEE address of the old adapter into the new one.
  6. Update the serial -> port in configuration.yaml. In some cases you may also need to update the baud rate if coming from an older adapter.
  7. Start Zigbee2MQTT.

If re-pairing was required, the FAQ’s next step is to disconnect power from all mains-powered devices and start re-pairing devices one by one. That is the part people underestimate. Forty devices is forty interviews, and battery devices need to be woken.

Post-swap triage before you declare failure

Two cheap steps come before starting over.

If re-pairing was not required and devices do not respond, the documented remedy is to restart some routers by removing them from mains power for a few seconds. Routers re-establish their parent relationships; end devices follow.

If pairing new devices is not working, the documented remedy is to re-pair some routers close to the coordinator while only permitting joining via the coordinator. Pairing should then work via the routers you re-paired. This is a targeted repair, not a full network rebuild.

What this procedure does not cover

A coordinator swap and a network_key, pan_id, or channel change are different operations with different consequences. Conflating them is how people re-pair a house unnecessarily, or fail to re-pair when they actually had to.

If your goal is to change the network key or PAN ID, the FAQ is unambiguous: you need to re-pair all devices. If your goal is to change the channel, it might require re-pairing some devices. Neither of those is a coordinator swap, and neither is solved by moving a key to a new stick.

Updating or downgrading Zigbee2MQTT, and updating coordinator firmware, do not require re-pairing. If your actual problem is a firmware bug or a version regression, a coordinator swap is not the fix.

When a plain switch or a mechanical timer is the better answer

If the devices you are worried about losing are a handful of lights and a thermostat, and the coordinator swap is happening because the old stick is flaky, consider whether the automation layer is earning its keep. A mechanical timer on a porch light and a plain wall switch on a hallway light do not need a coordinator, a backup file, or a re-pair. The reliability engineering question is not “how do I migrate forty devices” but “which of these forty devices actually need to be on the network.”

That audit is worth doing before the swap, not after. A related exercise is described in How to Audit the Small Systems That Quietly Run Your Week, which is about identifying which small systems are load-bearing and which are decorative. A coordinator swap is a good moment to demote a few devices to dumb hardware.

FAQ

Can I just copy the network key to the new coordinator?

No. The documented workflow does not include a key-transfer step. The network key is one of the parameters whose change forces re-pairing, not a credential you move between coordinators. What you copy in the no-re-pair path is the IEEE address of the old adapter into the new one.

I am going from a CC2531 to a CC2652. Both are zstack. Why does the FAQ say re-pairing is required?

Because the exception is about Z-Stack generation, not the adapter family label. CC2531 and CC2530 are Z-Stack 1.2. CC2652 and CC1352 are Z-Stack 3. The FAQ lists that jump as a re-pair case.

I am going from zstack to ember. The FAQ says re-pairing might not be required. Can I count on that?

No. The same sentence says results might vary and the path is not officially supported. Plan for a re-pair, attempt the no-re-pair path, and verify device by device. If some devices work and some do not, re-pair the ones that do not.

My devices stopped responding after a no-re-pair swap. Is the migration broken?

Not necessarily. The documented first step is to restart some routers by removing them from mains power for a few seconds. If new-device pairing is the problem rather than existing devices, re-pair some routers close to the coordinator while only permitting joining via the coordinator.

Do I need to re-pair if I only update coordinator firmware?

No. The FAQ lists updating coordinator firmware under operations that do not require re-pairing. If devices fail to respond after flashing, the documented remedies are to wait a few minutes for the network to settle, send commands to the device, and reboot the device.

Does this apply to ZHA?

The sources cited here cover Zigbee2MQTT. ZHA has its own migration behavior, and this article does not make claims about it.

Sources