Updated: 2026-10-04 · Applies to: home-assistant >=2025.11 (deCONZ: >=2025.10.1); slzb-os 2.9–3.x

Zigbee coordinator migration

Goal: move an existing Zigbee network to a new coordinator (e.g. Connect ZBT-2 or a network SLZB) or to different software (Zigbee2MQTT / deCONZ → ZHA) without re-pairing every device.
Prerequisites: HA 2025.11+, a free USB port (or a USB hub), a fresh HA backup. ZBT-2 docs ZBT-2 draft

How it works

• The network is defined by settings stored on the coordinator: network key, PAN ID, channel and IEEE address. ZBT-2 docs SLZB-OS manual If the new coordinator gets the same settings, devices rejoin it without pairing.
• During migration in HA, the new adapter takes over the old adapter's IEEE address. Without that, many devices would need re-pairing. ZBT-2 docs
• ZHA can only migrate from its own format. A Z2M or deCONZ network is therefore first loaded into ZHA via the old adapter, and only then is the ZHA network moved to the new one. ZBT-2 docs

Which procedure to use

Source: ZBT-2 docs, SLZB-OS manual.

Before migrating (always)

1. Make an HA backup. It also contains the Zigbee coordinator settings from ZHA. ZBT-2 draft
2. Connect the new adapter via a USB extension cable, away from USB 3.0, SSDs and the router. With HA Container, map it into the container. ZBT-2 docs
3. Synthesis: note which devices are battery-powered. Those are the ones most likely to need re-pairing after migration.

Procedure A: ZHA → new adapter

According to ZBT-2 docs:

1. Settings > Devices & services. HA discovers the new adapter; select Add.
2. In the dialog, pick Migrate Zigbee to a new adapter.
3. Choose Recommended installation. HA backs up the old adapter and writes its settings to the new one.
4. Done. Devices rejoin, usually within an hour. Power-cycling them helps.
5. Unplug the old adapter.

Alternative from ZHA: in the ZHA integration, cog wheel → Migrate adapter → Migrate to a new adapter → pick the new adapter's port → Migrate automatically (recommended). Advanced migration lets you restore an older backup. ZBT-2 docs

Procedure B: Zigbee2MQTT → ZHA (with the old adapter)

According to ZBT-2 docs:

1. Stop the Z2M app (Settings > Apps).
2. Remove Z2M devices from MQTT: either delete the whole MQTT integration (if you don't use MQTT elsewhere) or individual devices. Otherwise dead devices from MQTT discovery stay in HA.
3. Add the ZHA integration and select the serial port of the old adapter.
4. Advanced setup → Keep adapter network settings. ZHA takes over the network from the old adapter.
5. Continue with procedure A.

Procedure C: Zigbee2MQTT from a backup (old adapter gone)

According to ZBT-2 docs:

1. In the Z2M web UI, Settings > Tools > Request Z2M backup and download it. The ZIP contains coordinator_backup.json.
2. Stop Z2M and remove Z2M devices from MQTT (as in B, step 2).
3. Connect the new adapter, Add → Use as Zigbee adapter → Custom → Zigbee Home Automation.
4. In the Network Formation dialog, choose Upload a manual backup and upload coordinator_backup.json.
5. Assign the coordinator to an area and wait for devices to rejoin (usually within an hour).
6. Migrated devices get new entity IDs and lose manually assigned names. Update automations and dashboards.

Procedure D: deCONZ → ZHA

According to ZBT-2 docs:

1. Update the ConBee / RaspBee firmware to 26720700 or newer (deCONZ app → Settings > Gateway). HA must be 2025.10.1+.
2. In the deCONZ app, disable Start on boot and select Stop. Delete the deCONZ integration.
3. Add ZHA on the ConBee adapter → Advanced setup → Keep adapter network settings.
4. Wait for devices to rejoin. Battery devices may need manual re-pairing.
5. Continue with procedure A.

Procedure E: swapping a CC26xx adapter without changing software (e.g. to SLZB)

According to SLZB-OS manual, for adapters with a CC26xx chip (e.g. CC2652P7):

1. Stop Z2M or ZHA and power off the old coordinator.
2. Power off all Zigbee routers for at least 15 s (e.g. briefly switch off the breaker).
3. Power on the new coordinator, then the routers, then start Z2M or ZHA with the new adapter.
4. Devices should reconnect within 5–10 minutes.
5. If not: in SLZB-OS set the new coordinator's IEEE address to the old one (ADVANCED: Adapter IEEE address change) and repeat steps 1–4. Doesn't work in USB mode.

Synthesis: with ZHA it's simpler to use procedure A and enter the SLZB socket as the new port. SLZB-OS's configuration generator prints the values. SLZB-OS manual See Home Assistant Connect SLZB.

What doesn't carry over

• Device names, and for procedure C also entity IDs. Automations and dashboards need updating. ZBT-2 docs
• Battery devices sometimes have to be re-paired. Mains-powered devices usually rejoin on their own. ZBT-2 docs
• Settings beyond the network itself: there is no procedure that carries over everything. ZBT-2 docs

Verification

• Devices are available again in ZHA (or Z2M), mains-powered ones usually within an hour. ZBT-2 docs
• On a ZBT-2 the status LED is off, i.e. normal operation. ZBT-2 docs
• Synthesis: check that battery sensors report new values, not just that they appear in the list.

Rollback

• Don't use the old adapter with the same HA after migration. It has the same IEEE address as the new one. ZBT-2 docs
• Removing the integration does not reset the adapter; the network stays on the old adapter. ZBT-2 draft Synthesis: going back is therefore possible by migrating back (procedure A in reverse), not by simply swapping the adapters.
• Once you've confirmed the migration, reset the old adapter before selling or handing it over (ZBT-2: button, wipes the entire NVRAM). ZBT-2 docs

Troubleshooting

• Repair "Zigbee network settings have changed" after loading a Z2M network into ZHA → choose Keep the new settings. ZBT-2 docs
• Devices unavailable: power-cycle them. Tie an end device to a nearer router via Add devices via this device. Pair in the final location and routers first. ZBT-2 docs
• Network formation refused / commissioning timed out (SLZB): a network with the same PAN ID or Extended PAN ID exists nearby, or there is heavy interference. Move the coordinator away from the Wi-Fi router. SLZB-OS manual
• Interference in general: see Zigbee.

Related

• Zigbee, ZHA, Zigbee2MQTT, Connect ZBT-2, MQTT

Sources

• ZBT-2 docs: official migration procedures for ZHA, Z2M, Z2M from backup and deCONZ (Nabu Casa, 2025–2026).
• SLZB-OS manual: swapping a CC26xx adapter and the IEEE address (SLZB-OS).
• ZBT-2 draft: HA backups and removing the integration (draft, superseded).