Zigbee Troubleshooting

Zigbee failures become much easier to diagnose when you first decide which layer is failing. A missing serial port is not a mesh problem; one unsupported sensor is not proof of a bad coordinator; and a whole floor dropping offline is unlikely to be ten simultaneous device failures.

This guide starts after the host can open the serial port and the radio responds with coordinator firmware. If either prerequisite fails, begin with TI CC Series Radios Troubleshooting.

Before changing anything

Protect the working parts of the network before troubleshooting the broken part.

1. Make a current backup. Keep both the application's configuration/database and its coordinator-network backup where your normal host failure cannot destroy them.
2. Save the logs. Capture the startup or failure period before restarting repeatedly.
3. Record the current state. Note the application version, coordinator firmware, serial path, Zigbee channel, PAN ID and what changed before the fault began.
4. Change one variable at a time. Replacing the adapter, upgrading firmware, moving the coordinator and changing channel together destroys useful evidence.
5. Do not delete devices casually. A device can often rejoin the same network without being removed. Deleting it may also remove its name, groups, bindings, automations and history associations.

If the network is mostly working, treat a full reset and re-pair as the last option rather than a universal cure.

Quick symptom map

Symptom	Most likely area	Start here
The application cannot open or initialise the adapter	Serial path, port ownership, adapter settings or firmware	Application cannot connect
Every device becomes unavailable at once	Coordinator/application stopped, serial disconnect or network state mismatch	Whole network disappeared
A new device is never discovered	Joining not permitted, device not reset, poor path or unsupported commissioning	Device will not join
A device appears, but setup never completes	Sleepy device, weak link or failed interview/configuration	Interview fails
One existing device is unreliable	Battery, power, parent/router path, local interference or device fault	One device drops out
A room or floor is unreliable	Missing/poor router path, obstruction or local interference	Mesh coverage
Commands are delayed or arrive inconsistently	Congestion, retries, weak mesh, application load or excessive individual commands	Delays
Problems correlate with Wi-Fi or storage traffic	2.4 GHz interference or USB 3 noise	Interference
Trouble started after moving or replacing the adapter	Incomplete backup/restore, changed network identity or duplicate coordinator	Migration

Know the three device roles

A small amount of Zigbee vocabulary prevents many false diagnoses:

• The coordinator creates and manages the network. There is one coordinator per Zigbee network.
• A router is normally a permanently powered device that can relay packets and accept child devices. Smart plugs and dedicated repeaters commonly route; product behaviour varies.
• An end device does not route. Battery devices are usually sleepy end devices that wake briefly, exchange data with a parent, then go back to sleep.

The host running Zigbee2MQTT, ZHA or another application is not itself the mesh, even when the coordinator is plugged into it. MQTT, Home Assistant and dashboards sit above the Zigbee network and can fail independently.

Build the routing backbone first

A reliable Zigbee network needs enough always-on routers between the coordinator and its end devices. Routers shorten radio paths, carry traffic around obstacles and give the mesh alternatives when a device or route fails. This redundancy is what makes a mesh resilient.

Add well-distributed routers before adding large numbers of battery devices. Important areas should have more than one plausible route—not one distant smart plug or a bulb that disappears whenever its wall switch is turned off. Coordinator transmit power cannot replace this routing backbone because every device still has to send a reply.

The application cannot connect to the coordinator

An SRSP/SYS ping error in Zigbee2MQTT, a ZHA initialisation error or a similar startup failure happens before ordinary mesh routing matters.

Check these in order:

1. The configured path matches the connected radio. On Linux, prefer /dev/serial/by-id/... for a USB stick or /dev/serial0 for a HAT; names such as /dev/ttyUSB0 can change after a reboot.
2. Only one process owns the serial port. Stop other Zigbee applications, serial monitors and flashing tools.
3. Coordinator firmware—not the factory blink test or router firmware—is installed.
4. The application uses the correct radio family. Electrolama CC13x2/CC26x2 coordinators use TI ZNP, called zstack by Zigbee2MQTT and znp by ZHA.
5. Serial settings are correct. Zigbee2MQTT currently defaults to 115200 baud and hardware flow control disabled, which are appropriate for these radios; normally neither default needs to be written explicitly.
6. A container or virtual machine has the serial device mapped with read/write permission. Confirm the path inside the container, not just on the host.
7. The USB device is not repeatedly disconnecting in the host log. If it is, investigate the cable, port, power supply and USB hardware.

Do not erase the coordinator merely because the application cannot open its port. First verify the serial transport with the ZNP test described in TI CC Series Radios Troubleshooting.

It works after one restart but not reliably

An intermittent startup problem points more strongly to port ownership, USB passthrough, host power, a changing device path or service start order than to a bad mesh.

• Check whether another service probes serial devices during boot.
• Use the stable by-ID path rather than a numbered port.
• In containers, verify that device mapping survives host reboots.
• Inspect the host log for disconnect/reconnect events at the same timestamp.
• Avoid putting a network-attached serial adapter across an unreliable Wi-Fi, VPN or WAN path.

The whole network disappeared

When every device fails at almost the same moment, start at the common point: the coordinator, its application and the host.

1. Confirm that the application is running and its UI/API or MQTT bridge is healthy.
2. Confirm that it still owns the expected serial device and has not created a new, empty network.
3. Look for a host reboot, USB reset, storage failure or application upgrade at the failure time.
4. Compare the current channel, PAN ID, extended PAN ID and coordinator IEEE address with the saved network state where the application exposes them.
5. Check whether an old coordinator or a restored clone is also powered nearby.

After a normal application restart, routers generally return first. Battery devices may not appear until their next scheduled report or physical wake-up. Do not immediately reset every sleepy device just because the UI is still repopulating.

If the application shows an empty network after a storage or migration event, stop and restore the known-good application and coordinator backup. Starting fresh and pairing a test device can overwrite the evidence or make recovery more confusing.

A device will not join

Joining has several stages: the network permits joining, the device searches, security credentials are exchanged, and the application interviews the device to learn its capabilities. “Pairing failed” can mean failure at any of these stages.

Use a repeatable joining sequence

1. Check the application's supported-device information for the exact model number and its reset/join procedure.
2. Fit a known-good battery or provide stable power. A new device can still arrive with a weak battery.
3. Factory-reset the device. Removing it from a previous app or hub does not necessarily reset its Zigbee network state.
4. Open permit-join in the application for a limited time.
5. Put the device into join mode and watch the live application log.
6. Keep a sleepy device awake during discovery and interview, usually by following its documented button-press sequence.
7. Close permit-join when finished.

Normally, pair a device where it will be installed so it can discover a useful nearby router. If that fails, pairing close to the coordinator is a valuable diagnostic test. A successful close-range join followed by failure at the final location points to coverage, router compatibility or interference rather than device support.

Zigbee2MQTT can permit joining through a selected coordinator or router. This can help diagnose an awkward route, but it does not guarantee that the device will keep that parent forever.

Nothing appears in the log

If there is no join attempt at all:

• Confirm that permit-join actually opened and has not timed out.
• Repeat the manufacturer's factory-reset sequence precisely; indicator flashes are often significant.
• Ensure the device is Zigbee, not a visually identical Bluetooth, Wi-Fi, proprietary or region-specific model.
• Move it temporarily within a metre or two of the coordinator, while still keeping the coordinator away from the host and USB 3 noise.
• Try a fresh battery and keep the device awake.
• If it belonged to another Zigbee network, reset it rather than only deleting it from that system.
• Check whether the device requires an install code, QR-code commissioning, Touchlink or another joining method your application does not support.

If several known-good devices also cannot join, investigate whether joining is genuinely enabled, the network has a healthy router/coordinator path, and the coordinator state is intact.

The device joins but the interview or configuration fails

Discovery proves only that some radio exchange succeeded. During the interview, the application asks about endpoints, clusters, manufacturer information and capabilities. It may then configure attribute reporting and bindings. This is a longer conversation and exposes weak links or sleepy behaviour.

Try the following:

• Keep the device awake until the application reports a completed interview. Some battery products need repeated short button presses.
• Pair at the intended location with a good router nearby, or use a close-range attempt to separate range from compatibility.
• Retry after a factory reset; some devices need more than one attempt.
• Update the host application and its device definitions/converters.
• Check support using the exact model identifier, not only the retail name or appearance.
• If the device joined but is marked unsupported, preserve its model ID, manufacturer name, endpoints and clusters for a support request.

Do not confuse unsupported with failed interview. An unsupported device may have completed the Zigbee interview perfectly, but the application lacks the translation that turns its manufacturer-specific data into friendly controls. Conversely, a supported model cannot be identified if the interview never retrieves its identity.

For Zigbee2MQTT, use its supported-device database and pairing instructions. For ZHA, consult its device-support and diagnostics guidance.

The device paired but controls or entities are missing

First decide whether the data is missing from Zigbee or only from the home-automation UI.

• Inspect the device in Zigbee2MQTT or ZHA before debugging dashboards and automations.
• Check the device's documented exposes/entities. Similar-looking models can support different features.
• Wake battery devices before reconfiguring or reading attributes.
• Run the application's reconfigure operation if one is available.
• Rejoin the device without deleting it; many applications retain its identity and configuration.
• Update the application/device handlers before creating custom converters or quirks.

Some devices report only when a value changes or after a long maximum interval. A temperature sensor that has not published for twenty minutes is not necessarily offline. Likewise, battery percentage is often an estimate derived from voltage, and may update slowly or non-linearly.

If Zigbee data is arriving but an entity is absent in Home Assistant, the fault is at the integration or discovery layer, not in RF. Capture both the Zigbee application's device information and the consuming application's logs.

One device drops out or stops reporting

When the rest of the network is healthy, concentrate on what is unique to that device and location.

1. Check whether it is battery-powered and expected to sleep.
2. Trigger it physically and watch the live log. A fresh report proves more than an old availability badge.
3. Replace or measure its battery rather than trusting the reported percentage alone.
4. Check for switched-off routers between it and the rest of the mesh.
5. Move a known-good router closer, or temporarily move the device, then observe it over its normal reporting interval.
6. Look for local metalwork, appliances, Wi-Fi equipment or other interference.
7. Power-cycle a mains-powered device; for a battery device, wake it and attempt a rejoin to the same network.
8. Check for device firmware updates and known model-specific behaviour.

A rejoin is different from removing and adding the device as new. When possible, put the existing device back into join mode while the same network permits joins. It can refresh its connection while retaining the same IEEE identity and application configuration.

It fails at the same time every day

Regular timing is a valuable clue. Compare failures with:

• scheduled backups or large transfers to USB 3 storage;
• Wi-Fi cameras, streaming or access-point channel changes;
• heating equipment, lighting power supplies or appliances switching;
• host CPU, memory or storage pressure;
• an automation flooding the network with repeated individual commands;
• a router device being switched off at the wall.

Correlate timestamps before changing hardware.

Build and read the mesh

A coordinator forms the network, but routers make a larger network robust. Add permanently powered routing devices before expecting distant battery sensors to be reliable.

Good mesh design has:

• several compatible, permanently powered routers distributed through the property;
• more than one plausible path from important areas back toward the coordinator;
• routers on both sides of dense walls, floors or metal obstacles;
• the coordinator in the open, away from its host and other radios;
• no critical path that depends on a smart bulb somebody turns off with a wall switch.

Dedicated repeaters and smart plugs often make more predictable infrastructure than bulbs. A mains-powered product is often a router, not always one; verify how the application identifies it. Battery devices generally do not route.

Think in terms of overlapping cells rather than a chain stretched to its limit. If removing or powering off any single router isolates a room, that area has coverage but little resilience. Add another always-on router in a different useful position so the network has an alternative path.

Router count alone is not the target. Placement matters: several routers beside the coordinator cannot help an end device beyond two dense walls. Spread them through the occupied area, across floors and around major obstructions. Keep them powered continuously and allow the mesh time to repair after moving or adding them.

What a network map can and cannot tell you

A topology map is a snapshot of neighbour and route information reported by devices. It is useful for finding isolated areas, unexpected parents or missing routers, but it is not a live RF heat map.

• A missing line to a sleepy end device can be normal.
• Link-quality values are directional and implementation-dependent.
• A line does not prove that the path stays good throughout the day.
• Devices can change parents and routes without matching the tidy layout you expected.
• Generating a detailed map can itself create management traffic and briefly reduce responsiveness.

Use maps alongside packet failures, last-seen times and controlled physical tests. Do not rebuild a working mesh just to make the diagram prettier.

After adding or moving routers

Leave the network powered and allow it time to repair routes. Wake troublesome battery devices so they can communicate. Some sticky end devices do not choose a new parent readily; a rejoin in the installed location may be needed.

Commands are delayed or only sometimes work

Delay means a packet, acknowledgement or application action waited somewhere. Determine whether the delay affects Zigbee itself or a layer above it.

• Operate the device from the Zigbee application's own interface. If that is prompt but Home Assistant or another controller is slow, investigate MQTT, integrations and automations.
• Watch whether the command is sent immediately but acknowledged late or not at all.
• Compare one device, one room and the whole network.
• Check for repeated retries, route errors and an unhealthy router near affected devices.
• Look for bursts of traffic from reporting, polling, OTA updates or automations.
• Use Zigbee groups for simultaneous control of many lights where supported. One group command consumes less airtime and usually gives a more coordinated result than a long sequence of individual commands.

Binding can let a remote control a light or group without round-tripping through the coordinator application. It improves local resilience and response time, but must be configured correctly for the device endpoints and clusters.

Interference and poor range

Zigbee, 2.4 GHz Wi-Fi and Bluetooth share spectrum. USB 3 devices, storage adapters, computers and poorly shielded cables can also raise the local noise floor. For the approachable explanation of antennas, SNR, Wi-Fi overlap and USB 3 EMI, read RF Fundamentals for Zigbee and Thread.

The high-value fixes are:

• Move a USB coordinator away from the host using a good-quality shielded extension cable.
• Keep its antenna away from USB 3 storage, hubs, other radios, power supplies and large metal objects.
• Prefer a USB 2 port or powered USB 2 hub for the coordinator.
• Use wired Ethernet for a dedicated gateway when practical.
• Place the coordinator in the open and reasonably central to the network.
• Use 20 MHz-wide 2.4 GHz Wi-Fi and move capable high-traffic clients to 5 or 6 GHz.
• Build useful router paths instead of relying on coordinator transmit power alone.

Range cannot be guaranteed from a coordinator specification. Building materials, neighbouring networks, antenna orientation, receiver noise and router placement all affect the result.

Channel selection

Do not change the Zigbee channel merely because one device had a bad afternoon. First create physical separation, inspect nearby Wi-Fi use and establish whether the fault affects an area or the entire network.

For many installations, Zigbee channels 15, 20 or 25 are useful starting points for coexistence and device compatibility. They are not universally quiet: neighbouring Wi-Fi, regional channels and local noise determine the real result. Channel 26 can be attractive at the top of the band but has compatibility or transmit-power limitations on some products.

Before changing an established network:

1. Make a current backup.
2. Confirm that every important device supports the target channel.
3. Read the application's current channel-migration procedure.
4. Expect sleepy devices to take time to return; wake or power-cycle them if instructed.
5. Keep the old settings and logs until the migration is proven stable.

Where possible, first move your own Wi-Fi to a fixed, sensible 20 MHz channel. Wi-Fi clients generally follow their access point more gracefully than an established Zigbee mesh follows a channel change.

Coordinator failed to start because the PAN ID is in use

The PAN ID identifies a Zigbee network, while the extended PAN ID provides a larger identity. A conflict or network-state mismatch can appear after restoring data, moving between coordinators or accidentally creating another network.

Do not respond by randomly changing the PAN ID on an established system. Confirm which application data and coordinator state belong together. Restore the matching backup, or deliberately create a new network only when you accept that devices may need to be reset and paired again.

Also make sure an old coordinator restored with the same network identity is not operating nearby. A migrated coordinator and its clone must not run simultaneously on the same network identity.

Backups, restores and coordinator migration

A Zigbee installation contains state in more than one place. The coordinator holds network information; the host application holds device names, definitions, groups and integrations. A complete recovery plan protects both.

Before an application upgrade, firmware change, host move or coordinator migration:

• create a fresh backup using the application's supported mechanism;
• copy it away from the host being changed;
• record the coordinator model, firmware, channel and application version;
• verify that the target adapter and application support the intended restore path;
• keep the old coordinator powered off after a successful identity migration.

Use the migration function of the application that owns the network. A ZHA backup is intended for ZHA's restore/migration flow; a Zigbee2MQTT deployment should follow Zigbee2MQTT's current adapter backup and migration documentation. Do not assume that copying one database file transfers every required piece of state.

After migration, routers may return within minutes while sleepy devices reappear when they wake. Power-cycle mains devices or wake battery devices if the application's procedure recommends it. Re-pair only the stragglers, and do so without deleting them first where possible.

OTA firmware updates fail or make the network sluggish

Over-the-air updates transfer much more data than an ordinary sensor report. They can take a long time, consume shared airtime and expose marginal links.

• Update one device at a time unless the application explicitly manages concurrency.
• Keep the device powered, nearby and on a strong mesh path.
• Keep sleepy devices awake if their update procedure requires it.
• Avoid channel changes, coordinator restarts and other major work during an update.
• Do not power-cycle a device while it is applying firmware.
• If the network becomes slow, let the active update finish before diagnosing general congestion.

An offered update may be staged by the vendor or unavailable for a particular firmware branch. Use the application's live log to distinguish “no update available” from a failed transfer.

Devices show offline when they still work

Availability is an application policy, not a Zigbee truth oracle. Routers are expected to respond often and can usually be checked actively. Sleepy battery devices may be considered available based on how recently they reported, because they cannot answer while asleep.

If an offline device still reports when triggered:

• review the application's availability timeout and device-specific settings;
• compare its normal reporting interval with the timeout;
• check whether last_seen updates when the device is used;
• avoid aggressive polling of battery devices;
• distinguish a stale dashboard entity from the Zigbee application's own state.

Tune availability carefully. A very short timeout creates false alarms; a very long one hides real failures.

Can zzh run Zigbee and Bluetooth at the same time?

The CC2652R is a multiprotocol device, but the standard ZNP coordinator image used by this documentation runs Zigbee. Simultaneous Bluetooth operation requires different multiprotocol firmware and matching host support; it is not enabled by the normal coordinator setup.

Collect useful evidence

Good issue reports reduce guesswork. Capture:

• exact coordinator model, board revision and firmware version;
• host application and version;
• relevant configuration with passwords, network keys and private addresses removed;
• the log from before the failure through recovery, preferably at debug level for a short controlled reproduction;
• Zigbee channel and nearby 2.4 GHz Wi-Fi channel/width;
• device manufacturer, exact model ID and firmware;
• whether the device is a coordinator, router or end device;
• the scope: one device, one area or the whole network;
• a timeline of recent upgrades, migrations, power failures or placement changes;
• the troubleshooting experiments already performed and their results.

For ZHA device issues, download the device diagnostics and signature. For Zigbee2MQTT, include the interview result, device definition/support status and the relevant log—not the entire historical log directory.

Never publish a Zigbee network key, install code, Wi-Fi password, MQTT password or unredacted backup.

Before replacing hardware

Confirm all of the following:

• The radio passes a ZNP serial test.
• The application and coordinator firmware are suitable and current.
• Only one process owns the serial port.
• The application is using the expected network rather than a new empty one.
• The radio is physically separated from likely noise sources.
• A controlled test distinguishes one device from an area-wide or network-wide fault.
• Router coverage and permanent power are adequate.
• A current application and coordinator/network backup exists.
• Debug logs have been captured before destructive changes.

If those checks pass and the network still fails, test with one known-good device at a controlled distance and one known-good router. That result, combined with logs, is more useful than swapping several components at once.

Further reading

• Zigbee2MQTT: allowing devices to join
• Zigbee2MQTT FAQ
• Zigbee2MQTT OTA updates
• Home Assistant ZHA documentation and troubleshooting
• RF Fundamentals for Zigbee and Thread