Most Zigbee problems in Home Assistant look like device problems: a sensor that will not pair, a remote that responds a second late, a motion sensor that drops off every few days. The Home Assistant documentation traces many of them to the same few causes upstream: an outdated coordinator or old firmware, interference where the adapter is plugged in, and a mesh with too few routers.

This guide follows the advice in the Home Assistant ZHA documentation and the Zigbee2MQTT docs, in roughly the order you will need it when setting up a network or fixing a flaky one. Most of it applies whichever of the two you use.

How a Zigbee network is put together

Three kinds of devices make up the network:

  • The coordinator is the radio adapter connected to the machine running Home Assistant. A network has exactly one.
  • Routers are mains-powered devices such as plugs, many bulbs and some wall switches. They pass messages along for other devices.
  • End devices are usually battery-powered sensors and remotes. They sleep most of the time and talk through a parent, either the coordinator or a router.

Zigbee is a mesh network, so range and capacity come from routers, not from a stronger coordinator. The ZHA docs put it plainly: a healthy network needs many routers relatively close to each other.

There is also a hard limit on how many devices can attach directly to the coordinator. The zigpy library behind ZHA caps direct children at 32. That sounds low, but devices connected through routers do not count against it, so the same network can hold hundreds of devices in total. Coordinator firmware imposes such limits partly to push the network into a mesh layout instead of a star with everything hanging off the coordinator.

Pick a current coordinator

For ZHA, the Home Assistant documentation recommends the Home Assistant Connect ZBT-2 for anyone setting up a new network. Its firmware is maintained by the Home Assistant Zigbee team and can be updated from within Home Assistant. The older Connect ZBT-1 has been discontinued but is still fully supported, and the Home Assistant Green has no Zigbee radio of its own, so it needs an adapter too.

Other adapters the ZHA docs list as tested and working well:

  • Silicon Labs based: the Sonoff Zigbee 3.0 USB Dongle Plus "ZBDongle-E" (EFR32MG21) and the SMLIGHT SLZB-07.
  • Texas Instruments based: CC2652P, CC2652R, CC2652RB, CC1352P and CC1352R adapters flashed with Z-Stack coordinator firmware.
  • dresden elektronik: the ConBee III.

What to avoid matters as much. The ZHA docs no longer recommend CC2530/CC2531 sticks because they can only run very old, end-of-life firmware, and Zigbee2MQTT's network stability guide names the CC2530 and CC2531 as known poor performers. If you are still running one, the advice from both projects points the same way: replace it.

If you plan to use Zigbee2MQTT, check its supported adapters page first. It sorts adapters by stack into recommended (Texas Instruments zStack, Silicon Labs EmberZNet, deCONZ), not recommended, unmaintained (ZiGate) and experimental (ZBOSS), and notes that an adapter must be flashed with coordinator firmware before use, although some come preflashed. Only zStack and EmberZNet adapters currently support Zigbee2MQTT's coordinator backup.

Keep the connection local and wired

A coordinator talks to Home Assistant over a serial protocol, and the ZHA documentation explains that this protocol cannot cope with the packet loss and delay of an unstable link. It advises against running a coordinator through a serial-to-IP bridge over Wi-Fi, a WAN or a VPN. Zigbee2MQTT gives the same warning for Wi-Fi and suggests an Ethernet-connected adapter if a local USB one is not an option.

So: a USB adapter plugged into the Home Assistant machine, or a network coordinator on a cable. Not a Wi-Fi bridge.

Placement: the cheapest fix

Zigbee2MQTT's stability guide tells you not to underestimate this, and the fix rarely costs more than an extension cable.

  • Use a USB extension cable. Plugged straight into a computer or Raspberry Pi, the adapter picks up interference from the machine itself. Zigbee2MQTT says a 50 cm cable is already enough to reduce it, and both projects recommend a shielded one. The ZHA docs note that thicker cables usually have better shielding.
  • Use a USB 2.0 port. USB 3.x ports, devices and unshielded cables are well-known sources of 2.4 GHz noise. If the computer only has USB 3.x ports, the ZHA docs suggest a powered USB 2.0 hub. Zigbee2MQTT adds that putting the adapter right next to a USB or HDMI port can kill the radio signal entirely, and warns against placing it close to an SSD.
  • Move it away from Wi-Fi gear, power supplies and appliances. That includes your router and access points.
  • Aim for the middle of the house, away from walls, floors and ceilings, as far as that is practical.
  • Try different orientations. Both projects point out that rotating the adapter or its antenna can change link quality noticeably without moving it anywhere else. An extension cable makes that easy to test.

If the coordinator is built into the computer, the ZHA docs warn that a metal case can reduce its performance.

Leave the channel alone, fix Wi-Fi first

Zigbee uses channels 11 to 26, all in the 2.4 GHz band that Wi-Fi shares. ZHA's documented best practice is to keep its default channel. If you do change it, the general recommendation is 15, 20 or 25: those channels are less likely to overlap with Wi-Fi, and not every Zigbee device supports every channel.

When Wi-Fi and Zigbee do collide, the ZHA docs say it is usually better to set a fixed channel on your Wi-Fi router or access points first, before touching Zigbee. If you still decide to move Zigbee, ZHA has a Smart option under Settings > Connectivity > Zigbee > Network information that scans once and picks the best channel, preferring 15, 20 and 25. It does not keep monitoring afterwards. Devices can take up to an hour to follow the network to the new channel, and power cycling end devices speeds that up. In Zigbee2MQTT the channel is set in configuration.yaml, and its docs warn that changing it may require re-pairing some devices.

Wi-Fi is not the only competitor. Zigbee2MQTT lists Bluetooth, wireless gaming mice and keyboard receivers, and wireless audio transmitters, and points out that a second Zigbee system, such as an old Philips Hue bridge, should either hand its bulbs over or sit on a different channel.

Add routers before sensors

The order in which you build the network matters. The ZHA guidance is to start with mains-powered devices and only then add battery-operated ones. With routers already in place, a new sensor has somewhere close to attach to.

A few details make the difference between a router that helps and one that hurts:

  • Routers must stay powered. A bulb switched off at the wall stops routing, and the devices that relied on it have to find another path. The ZHA docs say directly that you should not have a setup where routers are often powered off.
  • Not every mains device routes. Zigbee2MQTT notes that almost all AC-powered devices act as routers, with the exception of most relays that do not need a neutral wire.
  • Router quality varies. Some devices route much better than others. Zigbee2MQTT gives some versions of the Sonoff S26R2ZB plug as an example of a limited router and says AwoX devices are known to cause network problems. ZHA lists Xiaomi and Aqara devices as known not to work with routers from several brands, including Ledvance/OSRAM and SmartThings, and suggests IKEA mains devices or dedicated DIY routers as a better choice.
  • A spare adapter can be a router. Some coordinator sticks also have router firmware, which gives you a dedicated, always-on router you can place where the mesh is weak.

Pair devices where they will live

When you add a device, do it at its final location. The ZHA docs warn that pairing next to the coordinator and then moving the device can leave it with a degraded connection.

Other pairing advice from the same page:

  • A device that was ever paired to another network usually needs a factory reset first.
  • Low batteries cause pairing failures on some devices. Some users found that replacing the battery in a brand new Xiaomi or Aqara sensor fixed it.
  • Some devices need several attempts. For Xiaomi and Aqara, which are not fully standards-compliant, the docs mention attempts lasting 10 to 20 minutes or longer.

Read the network map with care

ZHA's map (Settings > Connectivity > Zigbee > Show map) shows links between devices with their RSSI and LQI values. Use it to find devices with weak links, but do not over-interpret it.

  • Missing links on battery devices are normal. Sleepy end devices often vanish from a router's child table through a Zigbee 3.0 feature called child aging, yet keep working. If the device still reports state changes, it is connected.
  • RSSI is the more readable number. According to the ZHA docs, -60 dBm and above is a strong signal with very low risk of losing messages, and -80 dBm and below indicates a noisy environment where messages may get lost. It is measured to the first hop, which may be a router rather than the coordinator.
  • LQI is not comparable across vendors. The Zigbee and IEEE 802.15.4 specifications do not standardize how it is measured. Treat it as one data point combined with RSSI, not as a verdict.

Back up the network before you need it

ZHA backs up the Zigbee network automatically, and you can also make a manual backup from the configuration page. That backup is what lets you migrate to a new coordinator without re-pairing everything: under Settings > Connectivity > Zigbee, choose Migrate, plug in the new adapter and follow the steps. Migration works between Silicon Labs, Texas Instruments and ConBee/RaspBee adapters, as long as the old adapter was used in ZHA and not in deCONZ or Zigbee2MQTT.

During migration, ZHA may ask to overwrite the new radio's IEEE address with the old one. Accept it. Without that, the docs say you will have to reconnect many devices. Afterwards, do not run the old adapter in the same area unless you change its address. Expect devices to be unavailable for a while; they normally rejoin within an hour, faster if you power cycle them.

Zigbee2MQTT handles this differently and warns that moving to another adapter may in some cases require re-pairing all devices. Read its migration FAQ before buying a replacement.

Device firmware updates

ZHA can update the firmware of Zigbee devices through standard update entities, as long as the manufacturer publishes its firmware images. It includes update sources for IKEA, Inovelli, Ledvance/OSRAM, Sonoff and Third Reality. Ledvance, Sonoff, Inovelli and Third Reality are enabled by default; other providers are disabled by default because their updates may change or remove features or are only lightly tested. Before you install one, check whether you need it: the docs warn that an update can break features (group binding on some IKEA devices is their example) and, rarely, brick a device.

Put fresh batteries in before updating a battery device, and wake it with a button press or state change so it accepts the update. A device update usually takes about 10 minutes. If it takes much longer or fails, the ZHA docs point back to the same causes as everything else in this guide: poor reception and too few routers.