Category: Zigbee, ZHA & Zigbee2MQTT

When Zigbee sensors, plugs, or bulbs repeatedly show as unavailable in Home Assistant, the fastest fix is not always to re-pair everything. First determine whether the problem affects one device, a group of devices, or the entire Zigbee network. That pattern points toward very different causes.

1. Check the scope before changing anything

• One battery sensor: check its battery, physical location, and last-seen information.
• Several devices in one room: suspect weak mesh coverage, interference, or a nearby router/repeater issue.
• Most or all devices at once: inspect the coordinator, integration, host, and recent power or software changes.

Write down which devices are affected and when they last responded. Avoid deleting devices or resetting the coordinator until you have this baseline.

2. Check the integration and coordinator

Open the relevant integration—ZHA or Zigbee2MQTT—and look for a disconnected coordinator, startup errors, serial-port errors, or repeated reconnects. If the whole network went offline after a Home Assistant restart, USB change, host reboot, or power outage, investigate that event first.

For a USB coordinator, confirm that it still uses the expected device path. A changing device name can cause the integration to point at the wrong serial device. If you use a USB extension cable, check that the connection is secure and the coordinator is not pressed against the host computer.

3. Reduce radio interference

Zigbee operates in the 2.4 GHz band, which is shared with Wi-Fi and other devices. A coordinator plugged directly into a computer or placed beside a Wi-Fi access point, USB 3 device, or metal enclosure can experience interference. Try a good-quality USB extension cable and place the coordinator in open space, away from the host and router.

Do not change Zigbee and Wi-Fi channels at random. Record the current channel and make one planned change at a time; changing channels can require some devices to reconnect or rebuild routes.

Separate a radio problem from an integration problem

If you use ZHA: check the ZHA integration status and its device or coordinator logs in Home Assistant. Confirm the configured radio path is the one currently exposed by your host.

If you use Zigbee2MQTT: check both the Zigbee2MQTT frontend/log and the MQTT broker connection. A healthy MQTT connection does not prove the Zigbee coordinator is healthy, and a coordinator error is not fixed by changing an entity in Home Assistant.

If only one device is missing: inspect that device’s battery, last-seen information, location, and recent pairing or reset history before changing the whole network. If many devices disappeared together, start with the coordinator, integration, power, or routers.

For failures immediately following an outage, use the focused Zigbee power-outage recovery checklist. This article covers recurring dropouts across normal operation, not just post-outage recovery.

4. Test the mesh before re-pairing

Mains-powered Zigbee devices such as compatible smart plugs and dedicated repeaters can route traffic; most battery sensors do not. If devices at the edge of the home are unreliable, check whether there is a dependable router between them and the coordinator. Not every bulb is a good repeater, and some devices may behave poorly in mixed-vendor networks.

Move a suspect battery sensor temporarily closer to the coordinator and allow time for it to wake and report. If it becomes reliable nearby but not in its normal location, coverage or routing is a stronger suspect than the sensor itself.

5. Check batteries and device-specific behavior

Battery devices often sleep to conserve power. Their displayed battery percentage may update infrequently, so do not rely on that number alone. Replace a genuinely weak battery with the correct type, inspect contacts, and trigger the device according to its manufacturer’s instructions. Avoid repeatedly pressing pairing or reset buttons unless you intend to rejoin the device.

6. Use logs and change one variable at a time

Review Home Assistant and integration logs around the time the device disappeared. Look for coordinator disconnects, failed message delivery, interview failures, or repeated device timeouts. Record the time, affected devices, and any recent changes. Test one adjustment, wait long enough to observe the network, and compare the result.

When should you re-pair?

Re-pairing is reasonable when a single device remains unreachable after battery, range, and network checks, or when logs show that it has left the network. Before doing so, confirm that you have any needed device details and understand the steps for your integration. Do not factory-reset the entire Zigbee network to fix one sensor.

Quick checklist

1. Determine whether one, nearby, or all devices are affected.
2. Check coordinator and integration status.
3. Review recent power, host, USB, and software changes.
4. Improve coordinator placement and check interference.
5. Test mesh coverage and the device battery.
6. Review logs, then make one change at a time.

Frequently asked questions

Why do Zigbee devices become unavailable after a restart?

Some devices need time to wake and report, but widespread failures can indicate a coordinator connection, serial-path, or integration startup problem. Check whether the coordinator is online before resetting devices.

Should I change the Zigbee channel?

Only after checking interference and documenting the current configuration. A channel change can have side effects, so follow the instructions for ZHA or Zigbee2MQTT and test deliberately.

Does an unavailable device mean it is broken?

No. It can indicate weak coverage, a sleeping battery device, interference, a routing issue, or a coordinator problem. Diagnose the pattern first.

Image credit: Sebastian Scholz (Nuki) via Unsplash.

A Zigbee device that suddenly shows Unavailable in Home Assistant after a power outage is not necessarily broken. The outage may have restarted the coordinator, router devices, or the integration in a different order. Work through these checks before removing the device or rebuilding your Zigbee network.

1. Check whether the coordinator is online

Open the integration you use—ZHA or Zigbee2MQTT—and confirm that it is loaded and connected. If you use a USB coordinator, check that Home Assistant can still see its serial device. A changed USB path, loose connection, or coordinator that did not restart cleanly can make many devices appear unavailable at once.

• Check the integration status and its logs.
• Confirm the coordinator is powered and connected.
• If using USB, inspect the configured serial path and avoid unplugging it while the integration is running.
• Do not change the channel or restore a backup as a first step.

2. Look for a network-wide outage or one missing device

If many Zigbee devices went unavailable together, investigate the coordinator, integration, or power to Zigbee routers first. If only one battery sensor is missing, its battery or radio link may be the problem. Mains-powered Zigbee bulbs and plugs often act as routers; if several are still off after the outage, battery devices may have lost their usual route through the mesh.

3. Restore power in a sensible order

Make sure the coordinator and the Zigbee integration are running, then restore power to any mains-powered Zigbee routers that were switched off. Give the mesh time to settle. Wake a battery-powered sensor using its normal button or wake procedure, if its manufacturer supports one. Avoid repeatedly restarting everything; that makes it harder to tell which change helped.

4. Check logs before re-pairing

In ZHA or Zigbee2MQTT, inspect recent logs for coordinator disconnects, serial-port errors, failed interviews, or repeated communication timeouts. These point to different causes. A serial error suggests a coordinator or connection issue; repeated timeouts for one device suggest a range, battery, interference, or routing issue.

5. When should you re-pair the device?

Only consider re-pairing after the coordinator is stable, the integration is healthy, the device has power, and the logs suggest that the device itself is no longer communicating. Removing a device too early can discard its entity associations and create unnecessary setup work. If you do need to pair again, follow the device manufacturer’s reset instructions and your integration’s pairing procedure.

Quick diagnosis

What you see	Check first
Many devices unavailable	Coordinator, integration, and powered Zigbee routers
One battery sensor unavailable	Battery, wake procedure, range, and route
Serial-port or adapter error	USB connection, device path, and coordinator status
Device returns after waking	Battery-saving behavior and mesh reliability

Frequently asked questions

Will I lose my Zigbee devices if Home Assistant restarts?

Usually, a normal restart should not require re-pairing. If devices remain unavailable, diagnose the coordinator, integration, power, and radio path before deleting anything.

How long should I wait after power is restored?

Allow the coordinator and integration to become stable and give the mesh a few minutes to recover. Battery-powered devices may need to wake or report in before their status updates.

Bottom line: after a power outage, check the coordinator first, then the integration, powered routers, and individual devices. Re-pair only after those checks point to a device-specific problem.

Direct answer: The error “ZHA was not able to automatically detect serial port settings for your adapter” means Home Assistant cannot prove the coordinator’s complete transport profile. Confirm the stable device path or network socket, radio family, port ownership, permissions, firmware, baud rate, and flow control before deleting ZHA or resetting Zigbee devices.

This guide applies to Home Assistant OS, Supervised, Container, virtual-machine, and Core installations using ZHA with USB, internal, or network-attached Zigbee coordinators. The exact interface varies, but the safest order is hardware visibility, transport access, radio protocol, firmware validation, and only then Zigbee-network recovery.

This is a coordinator-layer failure, not an end-device pairing failure. Factory-resetting bulbs, sensors, switches, locks, or plugs cannot make Home Assistant open a coordinator port. It may instead erase useful pairing state and make recovery harder.

Exact symptoms and what they tell you

The message may appear during first-time ZHA setup, reconfiguration, or a radio migration. Home Assistant may show a possible serial device but ask for manual port settings, or it may fail before listing a usable coordinator.

If ZHA worked before a reboot, USB move, host update, container change, or firmware flash, that change is a strong clue. Record the sequence instead of changing several variables at once.

If ZHA connects but individual devices remain unavailable, the serial problem is already past. Continue with mesh routing, channel interference, sleeping-device check-in, and device-level diagnosis rather than repeating coordinator setup.

Before making changes

Record the coordinator’s exact model and hardware revision, installed firmware family and version, device path or redacted network endpoint, selected radio type, baud rate, flow-control mode, and recent changes. Save a current full Home Assistant backup and a ZHA coordinator backup when available.

Do not remove ZHA, erase the coordinator, flash firmware, or create a fresh Zigbee network as an opening move. ZHA’s migration and reconfiguration paths exist to preserve the existing network. Keep the old coordinator available until any migration is fully verified.

Never expose a network coordinator’s serial socket to the public internet. Keep it on a trusted LAN and redact network keys, tokens, MAC addresses, public IPs, precise locations, and unrelated device identifiers before sharing diagnostics.

Ranked diagnostic workflow

1. Confirm host-level hardware visibility

Why this branch ranks here: ZHA cannot probe a coordinator that the operating system or hypervisor does not expose.

Least-destructive diagnostic: In Home Assistant OS inspect Settings → System → Hardware. In a VM or container confirm the physical adapter is attached consistently to the Home Assistant guest and appears after reboot.

How to interpret the result: No device points to USB, power, cable, driver, or passthrough trouble. A device that appears and disappears suggests instability. A stable device lets you proceed to permissions and protocol selection.

Verified repair: Reconnect through a known-good data cable, correct the narrow documented passthrough, and use stable power. Avoid an unpowered hub.

Rollback: Restore the previous physical port and mapping if the adapter disappears after the change.

2. Use a persistent serial-by-id path

Why this branch ranks here: Short names such as /dev/ttyUSB0 or /dev/ttyACM0 may change when Linux enumerates devices differently.

Least-destructive diagnostic: Compare ZHA’s configured path with the current /dev/serial/by-id entry shown in hardware information. Verify the identifier belongs to the coordinator, not another USB serial device.

How to interpret the result: A changed short path explains a formerly working setup. A matching serial-by-id path makes renumbering less likely and moves attention to port ownership, permissions, parameters, or firmware.

Verified repair: Reconfigure the current radio to the stable serial-by-id path without deleting ZHA.

Rollback: Return to the recorded path if the identifier was chosen for the wrong hardware.

3. Identify the installed radio protocol

Why this branch ranks here: Similar product names and identical USB connectors can hide different chip families or firmware modes.

Least-destructive diagnostic: Use the coordinator manufacturer’s current documentation and the firmware actually installed. Match it to ZHA’s supported radio family instead of guessing from appearance.

How to interpret the result: A mismatched radio library can fail probing even while the serial port exists. Correct identification should produce a more specific connection result.

Verified repair: Select the documented Silicon Labs, Texas Instruments, deCONZ, XBee, ZiGate, or other supported radio type.

Rollback: Restore the prior selection if logs prove the new choice addresses a different protocol.

4. Release the coordinator port

Why this branch ranks here: A serial coordinator normally has one controlling application at a time.

Least-destructive diagnostic: Stop Zigbee2MQTT, terminal sessions, flashing tools, or any second integration aimed at the same path. Retry ZHA once and inspect the earliest log entry.

How to interpret the result: Success after releasing the port proves contention. Continued failure moves the investigation to permissions, serial parameters, firmware, or hardware reliability.

Verified repair: Assign each Zigbee stack its own coordinator and stable path. Never configure ZHA and Zigbee2MQTT to share one radio.

Rollback: Restart the former owner only when it is the intended Zigbee stack and ZHA should not use that adapter.

5. Verify permissions and passthrough

Why this branch ranks here: The host may list a serial device while Home Assistant lacks authority to open it.

Least-destructive diagnostic: Confirm the service, container, or guest has the documented device access. Avoid using broad privileged mode merely to see whether it helps.

How to interpret the result: Permission-denied or device-busy logs identify the transport boundary and do not prove coordinator failure. Correct access should let probing advance.

Verified repair: Correct only the necessary device mapping, group access, or VM attachment, then restart the affected service once.

Rollback: Restore the former security settings if the change is unrelated or grants excessive access.

6. Stabilize USB power and radio placement

Why this branch ranks here: Marginal power, faulty cables, hubs, and USB 3 interference can make identification intermittent.

Least-destructive diagnostic: Use a short shielded extension, avoid unpowered hubs, separate the coordinator from USB 3 equipment, and watch hardware logs for disconnects.

How to interpret the result: A stable path after relocation implicates the physical layer. A consistently stable adapter that still cannot probe points elsewhere.

Verified repair: Keep the reliable port, cable, power source, and spacing arrangement. Replace only a confirmed faulty component.

Rollback: Return to the prior arrangement if stability worsens, without erasing the Zigbee network.

7. Enter documented baud and flow-control values

Why this branch ranks here: Automatic probing cannot infer every nonstandard firmware profile.

Least-destructive diagnostic: Compare the manual serial settings with current instructions for the exact coordinator and installed firmware. Record existing values first.

How to interpret the result: A connection that succeeds with documented manual settings confirms an auto-detection mismatch, not a need to rebuild the network.

Verified repair: Save the supported baud rate and hardware, software, or no-flow-control setting.

Rollback: Restore the recorded values if communication becomes less reliable.

8. Validate firmware before flashing

Why this branch ranks here: Firmware may be incompatible, corrupt, or built for router mode rather than coordinator mode, but flashing has real recovery risk.

Least-destructive diagnostic: Compare the reported firmware family and version with the vendor’s ZHA-compatible coordinator release for the exact hardware revision.

How to interpret the result: A confirmed match argues against flashing. A confirmed mismatch justifies the vendor’s procedure after backups and stable power are in place.

Verified repair: Flash only the exact supported image using the manufacturer’s process and recovery instructions.

Rollback: Use the vendor’s recovery image and restore the coordinator backup only when the documented procedure calls for it.

9. Check network-coordinator transport

Why this branch ranks here: Ethernet and Wi-Fi radios add IP, DNS, TCP port, socket mode, client limits, and firewall variables.

Least-destructive diagnostic: Confirm the reserved local address, correct Zigbee socket port, socket service, and absence of another connected client. Test locally without public port forwarding.

How to interpret the result: Ping proves only IP reachability. Connection refused suggests a wrong port or disabled service; timeout suggests routing or firewall trouble.

Verified repair: Enable the documented local socket, reserve the address, and restrict access to the trusted LAN.

Rollback: Restore the former address and port when the device documentation contradicts the change.

10. Use ZHA migration rather than deletion

Why this branch ranks here: Replacing hardware safely requires preserving the coordinator network and its security material.

Least-destructive diagnostic: Use ZHA Configure → Migrate radio, select the new serial port, and choose the automatic migration backup or an appropriate known-good backup.

How to interpret the result: Successful migration should restore the network without mass re-pairing. Failure should be diagnosed before either radio is erased.

Verified repair: Complete the official migration workflow and retain the original coordinator until restart verification passes.

Rollback: Reconnect the original coordinator and restore its recorded settings if migration is incomplete.

11. Separate mesh recovery from transport recovery

Why this branch ranks here: Sleeping devices and routers may not all report immediately after the coordinator returns.

Least-destructive diagnostic: Confirm ZHA loads, the coordinator survives one controlled restart, and mains-powered routers begin updating before touching battery devices.

How to interpret the result: A healthy coordinator with isolated unavailable devices means the original serial error is repaired; remaining work is mesh or device specific.

Verified repair: Allow battery devices to check in and diagnose remaining nodes individually.

Rollback: Do not recreate the network just because one sleeping sensor has not reported yet.

Verification

Verification passes when ZHA loads without the exact serial-detection error, uses the intended stable path or local endpoint, and the selected radio library matches the installed firmware.

Restart Home Assistant once. The coordinator must reconnect automatically and remain stable. Existing devices should resume reporting without mass re-pairing; sleeping battery devices may require their normal check-in interval.

If the coordinator fails only after reboot, revisit persistent paths, VM or container passthrough, port ownership, reserved network addresses, and power. A one-time successful setup screen is not sufficient evidence.

Recovery and escalation

If a change makes the result worse, restore the recorded path, radio type, baud rate, flow control, mapping, or endpoint. Reverse only the last change so the evidence remains interpretable.

Escalate with installation type, Home Assistant version, coordinator model and revision, firmware family and version, stable path or redacted endpoint, radio type, serial parameters, and the earliest concise log lines. State what changed immediately before failure.

Safety and privacy

Do not share Zigbee network keys, backup archives, tokens, credentials, full diagnostics, public IPs, or precise locations. Review and redact every attachment before posting.

If Zigbee controls locks, alarms, heating, water valves, or safety equipment, provide manual control during maintenance. Do not flash firmware during unstable power or USB connectivity.

Prevention

Use a persistent serial-by-id path, stable power, a shielded extension away from USB 3 interference, separate coordinators for separate Zigbee stacks, and reserved addresses for network radios.

Keep both Home Assistant and coordinator backups current. Record the working radio type and serial profile before upgrades so recovery does not depend on memory.

Frequently asked diagnostic questions

Does “confirm host-level hardware visibility” mean the hardware is broken?

Not by itself. This check isolates one layer of the failure. No device points to USB, power, cable, driver, or passthrough trouble. A device that appears and disappears suggests instability. A stable device lets you proceed to permissions and protocol selection. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

Does “use a persistent serial-by-id path” mean the hardware is broken?

Not by itself. This check isolates one layer of the failure. A changed short path explains a formerly working setup. A matching serial-by-id path makes renumbering less likely and moves attention to port ownership, permissions, parameters, or firmware. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

Does “identify the installed radio protocol” mean the hardware is broken?

Not by itself. This check isolates one layer of the failure. A mismatched radio library can fail probing even while the serial port exists. Correct identification should produce a more specific connection result. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

Does “release the coordinator port” mean the hardware is broken?

Not by itself. This check isolates one layer of the failure. Success after releasing the port proves contention. Continued failure moves the investigation to permissions, serial parameters, firmware, or hardware reliability. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

Does “verify permissions and passthrough” mean the hardware is broken?

Not by itself. This check isolates one layer of the failure. Permission-denied or device-busy logs identify the transport boundary and do not prove coordinator failure. Correct access should let probing advance. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

Does “stabilize usb power and radio placement” mean the hardware is broken?

Not by itself. This check isolates one layer of the failure. A stable path after relocation implicates the physical layer. A consistently stable adapter that still cannot probe points elsewhere. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

Does “enter documented baud and flow-control values” mean the hardware is broken?

Not by itself. This check isolates one layer of the failure. A connection that succeeds with documented manual settings confirms an auto-detection mismatch, not a need to rebuild the network. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

Does “validate firmware before flashing” mean the hardware is broken?

Not by itself. This check isolates one layer of the failure. A confirmed match argues against flashing. A confirmed mismatch justifies the vendor’s procedure after backups and stable power are in place. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

Does “check network-coordinator transport” mean the hardware is broken?

Not by itself. This check isolates one layer of the failure. Ping proves only IP reachability. Connection refused suggests a wrong port or disabled service; timeout suggests routing or firewall trouble. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

Does “use zha migration rather than deletion” mean the hardware is broken?

Not by itself. This check isolates one layer of the failure. Successful migration should restore the network without mass re-pairing. Failure should be diagnosed before either radio is erased. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

Does “separate mesh recovery from transport recovery” mean the hardware is broken?

Not by itself. This check isolates one layer of the failure. A healthy coordinator with isolated unavailable devices means the original serial error is repaired; remaining work is mesh or device specific. Do not replace hardware until the relevant transport, permission, configuration, and software checks agree.

Related Troubliq resources

After transport recovery, use the ZHA pairing checklist, the post-update Zigbee recovery guide, and the Home Assistant Error Decoder.

Evidence and testing status

Last reviewed: September 28, 2026. Testing disclosure: The exact error wording, radio migration workflow, and coordinator concepts were checked against current Home Assistant documentation and Home Assistant Core source text. Troubliq did not reproduce every coordinator, firmware, hypervisor, container, or network-radio combination.

• Home Assistant ZHA documentation
• Home Assistant Core ZHA strings

Direct answer: A Zigbee2MQTT “interview failed” message means the device joined the Zigbee network but Zigbee2MQTT could not finish reading the descriptors, endpoints, clusters, or attributes needed to identify and control it. Keep battery devices awake, retry near a known-good coordinator or router, confirm the exact model is supported, and read the first failed interview step before changing firmware or rebuilding the network.

What “interview state failed” actually means

Joining and interviewing are separate. Joining establishes the device’s network relationship and security material. The interview then asks the device what it is: its node descriptor, active endpoints, supported clusters, manufacturer identifiers, and capabilities. A device can therefore appear in Zigbee2MQTT and still have no useful controls because the second stage did not complete.

Do not confuse this with a coordinator startup failure. If Zigbee2MQTT cannot open the adapter, the interview never begins. Likewise, an MQTT connection problem can prevent Home Assistant from seeing results even when the Zigbee interview succeeded. Use the first error in the log to identify the layer.

Symptoms and scope

• The log reports a successful join followed by interview failed or interview state failed.
• The device appears with an incomplete name, unsupported label, or no exposes.
• Pairing repeatedly stops at the same descriptor, endpoint, cluster, or attribute request.
• A battery device joins only while a button is pressed and then becomes silent.
• One model fails while other devices interview normally.
• Several models fail after a coordinator, firmware, channel, or network change.

Preserve evidence before retrying

Open the Zigbee2MQTT log and save the sequence from the first join message through the failure. Record the Zigbee2MQTT version, coordinator model and firmware, adapter type, Zigbee channel, installation method, device brand, printed model number, and any manufacturer/model identifiers shown in the log. Note whether permit-join targeted the coordinator or a router.

Back up the coordinator and Zigbee2MQTT data directory before updating firmware, changing channels, or modifying network keys. Redact network keys, MQTT credentials, IEEE addresses when unnecessary, public addresses, tokens, and other identifiers before sharing logs.

Ranked causes

Likely cause	Evidence	First safe test
Battery device fell asleep	Interview begins, then times out at varying steps	Use the manufacturer’s wake sequence throughout one retry
Weak or unstable parent link	Retries, timeouts, or success only very close to the coordinator	Interview near a known-good parent without moving the whole network
Unsupported fingerprint/converter	One exact model fails consistently while others work	Check the exact identifiers in the supported-device database
Low battery or unstable power	Device resets or leaves during interview	Install a fresh recommended battery or verify the power supply
Coordinator/firmware problem	Several unrelated devices fail after the same change	Check coordinator health and compatibility before updating again
2.4 GHz interference	Packet loss affects multiple devices or one location	Compare one controlled retry in a cleaner location
Stale partial entry	Repeated retries reuse an incomplete record	Remove only the failed device entry, reset that device, and retry

Step 1: confirm the exact model is supported

Search the official Zigbee2MQTT supported-devices database using the exact model identifier, not only the retail name. Manufacturers may reuse product names while changing internal hardware or fingerprints. A visually identical device can require a newer converter or expose different clusters.

If the device is listed, compare any pairing notes, required button sequence, and minimum Zigbee2MQTT version. If it is not listed, do not assume it is safe to substitute a similar converter. Preserve the interview log and identifiers for a device-support request. An open support issue is a report, not proof that all units are affected.

Step 2: keep sleepy devices awake

Battery devices often return to sleep before the interview completes. Follow the manufacturer or Zigbee2MQTT pairing instructions exactly. Some devices require repeated short presses, periodic presses, or holding a button until a light changes. Random rapid pressing can reset the device again or trigger a different mode.

Start permit-join first, reset the device, and maintain the documented wake action until the log reports a successful interview. If the failure advances farther each time, sleep or link reliability is more likely than an unsupported device. If it fails at the identical unsupported descriptor or converter step, investigate model support.

Step 3: choose the pairing parent deliberately

Interview once near the coordinator or a proven compatible mains-powered router. Zigbee2MQTT can permit joining through a selected device, which is useful when the final location depends on a router. Keep USB coordinators away from USB 3 equipment and other radio-noise sources using a quality extension cable where recommended.

Do not pair every device beside the coordinator and then move it across the building. Some end devices choose a parent during joining and may not immediately find a better route after relocation. A controlled close-range test is diagnostic; if it succeeds, remove the temporary entry, reset the device, and pair it in the intended location through an appropriate router.

Step 4: check power before software

Use a fresh battery of the correct chemistry and size when the existing battery is uncertain. A device may have enough voltage to blink or begin joining but still reset during sustained radio activity. For mains-powered products, stop if wiring, heat, swelling, odor, sparks, or moisture are involved; use a qualified electrician or the manufacturer rather than continuing software tests.

For USB-powered routers or coordinators, verify the cable and supply. Intermittent USB power can resemble a device interview problem when the coordinator silently reconnects. Check the host log for USB disconnects at the same timestamp.

Step 5: read which interview request failed

A node-descriptor timeout points toward the device not answering early in the process. Failure while discovering active endpoints may indicate sleep, link loss, or unusual firmware behavior. A consistent cluster or attribute-read failure can expose a converter expectation or nonstandard implementation. A manufacturer/model fingerprint mismatch points toward device support rather than radio range.

Use debug logging only long enough to reproduce one clean attempt, then return to the normal level. More logs are not automatically better; repeated attempts can bury the first meaningful exchange. Keep timestamps synchronized so coordinator, Zigbee2MQTT, and host messages can be compared.

Step 6: distinguish one-device failures from system failures

If one model fails while several known-good devices interview successfully in the same location, focus on its wake sequence, power, fingerprint, and support status. If unrelated devices all fail, inspect shared layers: coordinator connection, adapter firmware compatibility, host USB stability, Zigbee channel, permit-join state, and interference.

Do not change the Zigbee channel as an early experiment. Channel changes affect the entire network and sleepy devices may miss the update. First compare Wi-Fi channel use, coordinator placement, packet-loss symptoms, and a controlled short-range retry. If a channel change becomes justified, back up first and follow the official procedure.

Step 7: clear only the failed partial record

If Zigbee2MQTT retained an incomplete entry, remove that device entry only, then factory-reset that physical device according to its instructions. Confirm permit-join is enabled for the intended parent and retry once. Do not delete working devices, regenerate the network key, erase the coordinator, or create a new network.

After removal, verify that the next attempt receives a fresh join event. If no join appears, the device may not have reset, permit-join may have expired, or it may be attempting to rejoin through a parent that is unavailable.

Step 8: update only with evidence and rollback

Check the Zigbee2MQTT release notes and supported-device entry before updating. A newer converter may add the fingerprint you need, but updating every component simultaneously destroys the evidence showing which change mattered. Record the current version, preserve the data directory, update one layer, and repeat the same controlled interview.

Coordinator firmware changes carry greater risk. Confirm the exact adapter hardware, recommended firmware family, backup/restore path, and compatibility with the installed Zigbee stack. Never flash firmware intended for a similar-looking adapter. If the update does not improve the interview, restore the documented supported version when a safe rollback exists.

Interview versus reconfigure

An interview discovers what a newly joined device supports. Reconfigure is generally used after a device is already known, to repeat configuration such as binding or reporting where supported. Reconfigure does not replace a missing initial interview and cannot make an unknown fingerprint supported. Use the action that matches the failed stage.

If the interview completed and the device has correct exposes but updates are missing, reconfigure may be relevant. If the log still says interview failed and the device definition is incomplete, return to wake, link, power, and support checks.

How to verify a real fix

• The log explicitly reports a successful interview, not merely a successful join.
• The device page shows the expected manufacturer, model, endpoints, and exposes.
• A fresh device-originated state, measurement, or button event appears.
• One harmless command works where the device supports commands.
• The device remains available through its normal sleep/report interval.
• Zigbee2MQTT restarts once and recognizes the device without interviewing it again.

Validate with a lamp, sensor, or other non-safety-critical device action. Do not use locks, alarms, heaters, medical devices, garage doors, or hazardous loads as the first test.

Rollback and recovery

If a software or firmware update worsens the result, stop retrying and restore the prior supported state using its documented rollback process. Restore the Zigbee2MQTT data backup if configuration or device records were damaged. Do not restore an old network key or coordinator backup casually; the coordinator and database must describe the same network.

If the device joined but no longer responds after being moved, return it to the successful test location, wake it, and allow route repair. If that fails, remove only that device and pair again in the final location. Preserve automations and entity mappings before replacing a device record.

When to escalate

Escalate when the exact supported model fails repeatedly at the same interview step with fresh power and a strong link, when multiple devices began failing after a confirmed version change, or when coordinator disconnects appear. Include the device identifiers, Zigbee2MQTT version, coordinator and firmware, channel, installation method, selected pairing parent, wake procedure, and one sanitized debug log from join through failure.

For a new-device support request, follow the Zigbee2MQTT contributor instructions and provide the exact fingerprint rather than guessing a converter. Do not post network keys, MQTT passwords, tokens, or unnecessary IEEE addresses.

Prevention

• Build a stable router backbone before adding many battery devices.
• Pair devices in or near their intended location when practical.
• Keep coordinator firmware, Zigbee2MQTT version, and backup dates documented.
• Retain the manufacturer’s reset and wake instructions for each model.
• Use fresh batteries for first pairing when the supplied battery is uncertain.
• Update one layer at a time and test a known-good device afterward.

What to do when the interview succeeds only beside the coordinator

A close-range success proves that the device, coordinator, security exchange, and converter can complete an interview under favorable radio conditions. It does not prove the final location has a usable parent path. Do not leave a battery device paired beside the coordinator and simply move it across the home. Remove only that test entry, reset the device, and pair it again in its intended location through a stable mains-powered router when the device supports router-assisted joining.

If the same device still fails in its final location, compare one known-good device there, confirm the intended router remains powered, and inspect 2.4 GHz interference without changing the whole Zigbee channel immediately. The result distinguishes a placement or parent problem from a model-specific interview problem. Record which parent was used and whether the failure occurs at the same descriptor step; that detail makes escalation much more useful.

Evidence and testing disclosure

Applies to: current Zigbee2MQTT installations where a device joins but its interview fails. Expected result: Zigbee2MQTT completes the interview, selects a correct device definition, exposes expected capabilities, and receives a fresh state. Verification: use the explicit successful-interview log plus device-originated and controller-originated tests. Testing status: this guide is based on official Zigbee2MQTT documentation and protocol-layer diagnosis; Troubliq did not physically test every device model. Last reviewed September 29, 2026.

• Official Zigbee2MQTT pairing guide
• Official MQTT topics and interview-state documentation
• Official supported-devices database
• Official startup and adapter troubleshooting

Related Troubliq guides

For failures before an interview begins, see the coordinator and serial-port checklist. For ZHA pairing failures, use the ZHA pairing guide. You can also classify a sanitized message with the Home Assistant Error Decoder or browse the Zigbee troubleshooting hub.

Short answer: Put the Zigbee device close to the coordinator, confirm it is in a true factory-new pairing state, remove likely 2.4 GHz interference, and watch the ZHA pairing screen for evidence before repeating resets.

Applies to

Home Assistant using ZHA with a supported coordinator. Record the device model, coordinator model and firmware, Home Assistant version, and whether the device has ever joined another Zigbee network.

1. Check the coordinator first

Confirm that ZHA loads without an error and that existing Zigbee devices still respond. If the entire network is unavailable, do not reset the new device repeatedly; troubleshoot the coordinator connection, USB path, extension cable, power, and host first.

2. Use the exact reset sequence

Follow the manufacturer’s instructions for that exact model. A blinking light may indicate setup mode without proving that old network credentials were erased. Keep the device powered and close to the coordinator during the first attempt.

3. Open pairing once

Start Add Device in ZHA, trigger the device’s pairing sequence, and wait through the discovery window. Note whether ZHA sees nothing, begins an interview and fails, or completes but creates no usable entities. Those are different failure stages.

4. Reduce interference safely

Use a USB extension cable to move a USB coordinator away from the computer, SSDs, USB 3 equipment, and dense cabling. Temporarily move the device closer. Do not change Wi-Fi or Zigbee channels during an active pairing attempt.

5. Try one controlled retry

Close the pairing window, wait briefly, perform the documented reset again, and retry once. Battery devices may need a button tap during interview to remain awake. Replace a suspect battery with a known-good one if voltage is uncertain.

If the interview fails

Save redacted ZHA logs and note the stage or cluster that failed. Check current Home Assistant documentation and the manufacturer’s compatibility information. Community device handlers or quirks can help only when they match the exact model and firmware.

Last resort

Changing the coordinator, channel, or radio stack affects the whole mesh and requires a backup and recovery plan. Do not make network-wide changes to solve one unconfirmed device problem.

Official sources

• Home Assistant Zigbee Home Automation integration and troubleshooting

Last reviewed: September 4, 2026.

Find your next troubleshooting path

• Zigbee, ZHA and Zigbee2MQTT hub
• Zigbee2MQTT interview fails
• ZHA coordinator NCP failed state

Use the related guide that matches the next confirmed layer of the failure. Avoid changing unrelated systems at the same time.

Define the pairing failure precisely

“Will not pair” can mean that ZHA never discovers the device, discovers it but times out, creates an incomplete device, or adds it and then immediately loses it. Record the exact stage and message. Also note the device model, coordinator model, Home Assistant version, ZHA radio type, and whether the device was previously joined to another Zigbee network.

Test only one change per pairing attempt. Repeatedly pressing buttons, restarting Home Assistant, changing channels, and moving the device at the same time may eventually produce a join, but it hides the cause and makes the next failure harder to solve.

Confirm the coordinator is healthy

Before blaming the new device, verify that ZHA is loaded and existing Zigbee devices are operating normally. Review the coordinator and ZHA logs for serial-port errors, radio resets, database problems, or repeated reconnects. If the entire network is unstable, pause pairing work and protect the existing network first.

Check that no second application is trying to use the same coordinator. A radio cannot be controlled simultaneously by ZHA and another Zigbee stack. After a USB move, host restart, or virtualization change, confirm that Home Assistant still sees the intended adapter through the stable device path rather than a temporary port name.

Place the device close for the first join

Perform the initial test within a short, unobstructed distance of the coordinator while keeping the coordinator away from USB 3 devices, hubs, SSDs, and dense Wi-Fi equipment. This is a diagnostic position, not necessarily the device’s final location. A successful close-range join followed by failure at the destination points toward routing, interference, or coverage.

Use a USB extension cable when supported to separate the radio from the host. Do not place the coordinator inside a metal cabinet or directly beside an access point. If moving the radio changes the result, preserve that evidence before changing Zigbee or Wi-Fi channels.

Reset only according to the device procedure

A device that remembers a former Zigbee network may ignore a new permit-to-join window. Use the manufacturer’s exact reset or rejoin sequence for the model and watch its LED pattern or display confirmation. Similar-looking products sometimes use different hold times, button sequences, or power cycles.

Avoid endless factory resets. After one confirmed reset, reopen pairing in ZHA and follow the device’s join procedure once. If it still fails, collect logs and investigate the reported stage. Repeating the same action without new evidence can drain batteries and create partially initialized records.

Check power and sleepy-device behavior

Install a known-good battery with the correct chemistry and polarity, or verify stable mains power. A device may flash normally but brown out during radio transmission. For battery devices, keep the device awake during the interview using the documented short press or wake procedure; do not improvise rapid button presses unless the manual specifies them.

Sleepy end devices may pause during configuration and appear to time out. Keep them near the coordinator and allow the process to finish. If ZHA creates a device with missing entities, wait, wake it as documented, and review the device signature and interview status before deleting it.

Evaluate channel and interference evidence

Zigbee and 2.4 GHz Wi-Fi share spectrum. Check whether failures began after an access-point, channel, or coordinator change. A channel change is a network-wide operation, not a casual pairing trick, because some devices may need time or manual intervention to follow the network.

First reduce nearby interference and test at close range. If logs and repeated controlled tests support a channel conflict, plan any channel change with a coordinator backup and a recovery window. Do not rebuild a functioning mesh solely because one device has not yet joined.

Remove stale records carefully

If ZHA already contains an incomplete entry for the same device, inspect it before removal. Record the IEEE address and any entities or automations linked to the record. Remove only the failed entry you have identified, then perform one fresh join with logs enabled.

Do not delete unrelated devices or the ZHA integration. Removing the integration can affect the whole network and is disproportionate to a single pairing failure. If the coordinator database appears damaged, stop and create backups before attempting broader recovery.

Verify routing after a successful join

Once paired, leave the device powered near the coordinator until configuration completes. Then move it gradually to the intended location and test state changes and commands. Mains-powered Zigbee routers may need time to establish useful routes; battery devices generally do not repeat traffic for others.

Verify the repair after normal overnight operation and after any expected coordinator or Home Assistant restart. Record the final placement and the change that allowed pairing. If the device only works beside the coordinator, the pairing problem is solved but the mesh or interference problem remains.

When to escalate

Ask for model-specific help when ZHA consistently discovers the device but the interview fails at the same stage, the device signature appears incomplete, or the manufacturer’s documented reset procedure does not produce a join. Share sanitized pairing logs, the exact model, coordinator and firmware, Zigbee channel, Home Assistant version, and the distance used for the close-range test. Do not publish network keys, complete backups, serial-device identifiers, or unrelated logs. A narrow, reproducible report is far more useful than another sequence of untracked resets.

Detailed evidence checklist for Zigbee device will not pair with ZHA

Before another change, create a short incident record. Include the exact time the symptom appeared, what the system was doing, the last successful action, and every update or network change made during the previous day. Record the Home Assistant release, installation type, integration version, device model, firmware, connection method, current address, and relevant entity IDs. Screenshots are useful for visible states, but copy the exact error text because screenshots may crop the detail needed to search logs.

Compare the failing item with one known-good item that uses the same path. If both fail, move outward toward shared services such as the integration, coordinator, add-on, DNS, router, cloud account, or Home Assistant host. If only one fails, stay close to that device: power, signal, address, credentials, firmware, permissions, and configuration. This comparison prevents a single-device problem from turning into an unnecessary system-wide rebuild.

Network tests that prove the failing layer

Use tests in layers. Confirm the address is current in the router or DHCP server. Confirm the Home Assistant host or container resolves the same name and reaches the intended address. Then test the actual documented service, port, or protocol. A dashboard loading on a phone proves only the phone’s path. A successful ping proves basic reachability, not authentication, WebSocket upgrades, multicast discovery, API encryption, event subscriptions, or application permissions.

For segmented networks, document source VLAN, destination VLAN, direction, protocol, and port before editing a firewall rule. Test the smallest temporary exception and remove it if it did not help. Discovery traffic and control traffic may use different mechanisms. Seeing a device in discovery does not prove Home Assistant can maintain a working session.

Configuration comparison procedure

Export or photograph the current configuration without exposing secrets. Compare it with official documentation field by field: host, port, account, region, project, encryption setting, device identifier, and optional switches. Watch for trailing spaces, uppercase versus lowercase account names, obsolete hostnames, restored encryption keys, or an account belonging to the wrong home or region.

Use Reconfigure or Reauthenticate before deleting an integration. Preserve entity IDs and note every automation, dashboard, script, scene, or helper that refers to them. If replacement becomes necessary, take a backup and map old entities to replacements. That makes rollback controlled rather than leaving broken references.

Power, radio, and timing checks

Do not interpret every unavailable state as software failure. Low-voltage devices may stay partly online while unstable power causes resets. Battery devices sleep and report on their own schedule. Wi-Fi and Bluetooth devices can associate yet fail at the application layer. Zigbee and Z-Wave devices depend on routes, radio conditions, and powered repeaters. Match the test to the technology instead of repeatedly pressing Reload.

Allow enough time after each test. Cloud polling, sleepy devices, retained MQTT messages, mesh repair, Bluetooth advertisements, and DHCP changes do not update instantly. Define the expected interval, then wait through at least two normal cycles. If availability returns briefly, capture the next disconnect in logs instead of declaring success.

Log-reading workflow

Synchronize clocks and reproduce the problem once. Start with the first warning or error at that timestamp; later messages may be consequences. Group errors by layer: name resolution, timeout, refused connection, TLS certificate, unauthorized account, invalid token, missing permission, unsupported capability, malformed payload, device timeout, or rate limit. Each group suggests a different next action.

Turn debug logging off after reproduction. Large files consume storage and bury the event. Redact tokens, passwords, keys, email addresses, public addresses, precise locations, and unnecessary unique identifiers. Keep the unredacted copy private for comparison with later tests.

Safe change order

1. Correct time, power, cabling, or an obviously stale address.
2. Reload only the affected integration when documentation supports it.
3. Use Reconfigure or Reauthenticate without deleting the entry.
4. Restart only the affected device or add-on during a safe window.
5. Restart Home Assistant when several components share the symptom or a change requires it.
6. Update software after reading release notes and preserving rollback.
7. Delete, exclude, reset, or rebuild only after safer checks prove it necessary.

Post-repair validation

Verify both directions. Confirm Home Assistant receives a fresh state, send one harmless command, and confirm the physical response. Check the returned state, logbook, history, and automation trace. Restart the affected component and verify automatic reconnection. During a maintenance window, confirm the repair survives a normal Home Assistant restart.

Monitor long enough to cover the original pattern. If failure occurred overnight, after DHCP renewal, deep sleep, or token expiry, a five-minute test is insufficient. Record the confirmed cause and exact corrective change. Remove temporary firewall rules, extra logging, duplicate test integrations, and unused credentials.

When to stop and escalate

Stop if hardware overheats, power is unstable, storage reports errors, a controller backup fails, credentials are rejected across services, or firmware may be damaged. Escalate with versions, timestamps, topology, redacted logs, the first meaningful error, and results of each safe test. Do not repeat destructive steps while waiting for help.

A strong report answers four questions: What still works? What exactly fails? What changed immediately beforehand? Which test most clearly separates the causes? Those answers help maintainers diagnose the correct layer.