A Zigbee device that appears in ZHA, reaches most of the interview, and then fails is not the same problem as a device that never enters pairing mode. The radio has usually heard the device; the failure happens while Home Assistant requests endpoints, clusters, or basic attributes. That distinction prevents unnecessary coordinator resets.
What this failure pattern tells you
This guide uses a narrow diagnostic sequence: confirm the pattern, protect the current configuration, test the smallest likely cause, and verify the result before moving deeper. That approach avoids turning one failed device or automation into a site-wide recovery job.
- The device is discovered but remains partially configured or marked unavailable.
- The interview repeatedly stalls near completion.
- A battery device pairs only when held beside the coordinator.
- The same device worked before a battery change, migration, or factory reset.
Most likely causes
- The sleepy device stopped responding before the interview finished.
- The device still remembers an earlier Zigbee network.
- Weak signal or 2.4 GHz interference interrupted cluster discovery.
- The coordinator or router is busy after a restart.
- A manufacturer-specific quirk needs a fresh interview or newer device support.
Before changing anything
Make a current Home Assistant backup and download it somewhere outside the system. Take screenshots of the affected integration, device, entity IDs, and any relevant automation. Record the exact time of the next failure so the log window stays small. If the issue involves radio hardware, do not unplug it while Home Assistant is writing data.
Step-by-step diagnosis and repair
- Create a Home Assistant backup before changing the Zigbee network.
- Replace or fully charge the device battery; low voltage can allow pairing but fail sustained communication.
- Factory-reset the device using its manufacturer procedure, then keep it awake throughout the interview by tapping its pairing button every few seconds.
- Pair within a few feet of a powered Zigbee router or the coordinator, but keep USB coordinators away from USB 3 cables, hubs, Wi-Fi access points, and metal enclosures.
- In ZHA, remove only the failed device entry—not the coordinator—then start Add Device and retry once.
- If it still fails, restart Home Assistant once, wait for the Zigbee network to settle, and review Settings → System → Logs for ZHA, zigpy, endpoint, timeout, or unsupported-cluster messages.
- Test another known-good device. If only one model fails, treat it as device-specific rather than rebuilding the network.
How to verify the repair
Do not declare success immediately after a reload. Repeat the original action several times, then observe the system through at least one normal restart or reconnect cycle. Review the log at the exact test time and confirm that the affected entities update normally. If the problem was intermittent, keep a short note of the previous failure interval and monitor beyond it.
Common mistakes to avoid
- Do not delete the ZHA integration or erase the coordinator as a first step.
- Do not repeatedly power-cycle the coordinator during an interview.
- Do not assume a high percentage means the device is almost healthy; one missing endpoint can prevent usable configuration.
A practical decision rule
If several unrelated devices fail at the same moment, investigate shared infrastructure: power, network, broker, radio, host load, or a recent update. If only one model or entity fails while everything around it remains stable, focus on that device’s identity, firmware, configuration, and signal path. Rebuilding a healthy shared integration should be the final option, not the first.
When to restore a backup
Restore only when you can identify a known-good backup from before a harmful configuration change and you understand what newer changes will be lost. A backup is not a substitute for diagnosing failing hardware, interference, duplicate identifiers, or unstable power; those problems will return after restoration.
Frequently asked questions
Should I re-pair every Zigbee device?
No. A single interview failure rarely justifies rebuilding a working mesh.
Can Wi-Fi cause this?
Yes. Zigbee and 2.4 GHz Wi-Fi share spectrum, and proximity to access points or USB 3 equipment can make an intermittent failure look like a software bug.
When should I check device support?
After a clean reset, strong-signal pairing, and a second controlled attempt still fail for the same model.
Bottom line
Start with evidence from the affected device, integration, trace, or topic. Protect the working system, change one variable, and verify through the original failure condition. That is slower than random resets for five minutes and much faster than rebuilding an entire smart home unnecessarily.
Deep diagnostic worksheet
Use this worksheet when the quick repair does not hold. The objective is to build a timestamped explanation of the ZHA interview problem rather than accumulate unrelated changes. Keep credentials and private addresses out of screenshots or public reports.
- Record the device manufacturer, model, mains-or-battery status, pairing distance, and the exact stage where the interview stops. These details distinguish a sleepy end-device problem from a coordinator-wide problem.
- Open the device page and note which entities, endpoints, and diagnostic values were created. A partially created device proves that discovery occurred even if cluster interrogation did not finish.
- Compare the failure with a known-good Zigbee device paired from the same location. If the second device also struggles, investigate radio placement, interference, and coordinator health before blaming one product.
- For battery devices, keep the unit awake throughout pairing according to its manual. Many devices sleep quickly after joining, which can interrupt the exchange of endpoint and attribute information.
- Check the Home Assistant log at the exact pairing time. Preserve the manufacturer, model, IEEE address suffix, exception name, and retry sequence while removing credentials before sharing a report.
- Inspect whether the device was previously joined to another coordinator. A proper factory reset is model-specific; merely removing a battery often does not erase the former network.
- Move a USB coordinator away from USB 3 equipment and metal using a quality extension cable. Change only placement first; channel changes can require wider planning and should not be casual experiments.
- After a failed attempt, remove only the incomplete device, restart nothing unless logs indicate a stuck integration, and allow the mesh to settle before one controlled retry.
Failure-pattern examples
- Fails only with one battery sensor: replace the battery, perform the documented factory reset, pair close to a stable router or coordinator, and keep the sensor awake. Do not rebuild ZHA.
- Several new devices fail from every room: test radio placement, host load, coordinator connectivity, and interference. Preserve the network database and investigate shared infrastructure.
- Device joins and controls work but some entities are missing: allow time for initialization, check disabled entities, confirm model support, and collect signatures before considering a device handler issue.
- Pairing works beside the coordinator but not at installation location: the join succeeded; the mesh path is the likely weakness. Add or reposition appropriate powered routers rather than repeatedly pairing.
- Failure began after a host migration: confirm the correct serial device path, coordinator type, extension cable, and restored Zigbee data before changing device firmware.
Advanced notes that prevent false fixes
- Treat a high interview percentage as a progress indicator, not proof that the remaining step is unimportant.
- Avoid channel changes unless interference evidence supports them and you understand how every device will be affected.
- A custom quirk should be considered only after obtaining the complete device signature and checking existing support.
- Battery voltage reported by a device can lag; a fresh known-good battery is a stronger test than one stale percentage reading.
- Powered Zigbee routers must be compatible and placed where they provide a useful route, not clustered beside the coordinator.
- When reporting a bug, include reproducible steps, ZHA diagnostics, logs, coordinator model and firmware, Home Assistant version, and device signature.
Final verification checklist
Verification must reproduce the original condition. A page reload or one successful command is insufficient for an intermittent problem.
- Device remains available after the normal sleep interval.
- All expected endpoints and entities appear or unsupported ones are documented.
- A control or sensor update succeeds from the final installation location.
- The log contains no repeating interview retries.
- The test survives one normal Home Assistant restart.
- No unrelated Zigbee devices became unstable.
Official reference
Technical behavior and terminology were checked against Home Assistant ZHA documentation. Interface labels and capabilities can change, so use the current official page when your installed version differs.