Troubleshooting guide

Zigbee2MQTT Pairing Failed: What to Check When Permit Join Finds No Device

Category: Smart Home

You enabled permit join in Zigbee2MQTT, but your new Zigbee device never appears, leaving you stuck at the permit join never finds a device step.

Confirm permit join is actually active

Open the Zigbee2MQTT frontend and check the permit join countdown. If it shows zero or has already expired, click Permit join (all) again and watch the timer. A running countdown means the coordinator is accepting joins; a missing or instantly expiring timer points to a coordinator or configuration problem, not the device.

In the Zigbee2MQTT logs, look for the coordinator startup line and any recent errors. If the USB coordinator is not listed or shows repeated disconnects, reseat it in a powered USB port and restart Zigbee2MQTT. Then compare the Zigbee channel in your configuration with your Wi-Fi channel; a channel overlap (for example, Zigbee 11 near Wi-Fi 1) can prevent joins. Change the Zigbee channel only if you can re-pair existing devices, and note the old value so you can roll back.

Reset the device correctly

Put the device into pairing mode per its manual, usually a long press until an LED blinks. Keep it within a few meters of the coordinator during the attempt. If it still does not appear, remove its battery for ten seconds, replace it, and start permit join again before resetting.

Verification test

With permit join active, reset the device once more and watch the Zigbee2MQTT log for an incoming join or interview message. If a device line appears, pairing succeeded. If nothing appears after two attempts, the join never reached the coordinator; revisit the coordinator link and channel checks. This confirms whether the failure is radio-side or device-side.

If these steps do not resolve your zigbee2mqtt pairing failed state,

Zigbee2MQTT dashboard showing a paired device and MQTT state

Ask for help with your log excerpt and coordinator model.


Back to the service page · Ask about this exact symptom