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 failedorinterview 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.