Troubleshooting guide

Zigbee2MQTT Permit Join: When the New Device Never Appears

Category: Smart Home

You started permit join in Zigbee2MQTT, but your new Zigbee device never shows up in the devices list. Let’s walk through this calmly and find the break in the chain.

Confirm permit join is actually active

Open the Zigbee2MQTT frontend and check that the permit join countdown is visibly running. If the countdown expired, restart it and keep the window open while you work. Also confirm your USB coordinator is online: in the frontend, the coordinator status should show as connected, not offline or error. If it is offline, stop here and fix the coordinator connection first.

Check the device is in pairing mode

Most devices need a long press or a specific button sequence to enter pairing mode. A brief press is often not enough. Watch for a blinking LED or a confirmation flash. If you see no visual sign, remove and reinsert the battery, then repeat the manufacturer’s pairing sequence. Place the device within a few meters of the coordinator during this test.

Rule out network and interference issues

Bring the device close to the coordinator and try again. If it pairs at close range but not at its final location, the problem is range or interference, not permit join. Also check that your Zigbee channel is not overlapping a busy Wi-Fi channel; channels 11, 15, 20, and 25 are common choices.

Verification test

With permit join active and the device blinking in pairing mode, watch the Zigbee2MQTT log. A successful join shows an incoming device announcement and an interview starting. If the log stays silent for two minutes, the coordinator is not receiving the device’s join request.

Rollback and recovery

If you changed channel or coordinator settings during diagnosis, revert them and restart Zigbee2MQTT before retesting. If the device still never appears,

Zigbee2MQTT dashboard showing a paired device and MQTT state

Ask for help with your log excerpt and device model.

Remember: zigbee2mqtt permit join only opens the network; it cannot compensate for a device that never transmits a join request.


Back to the service page · Ask about this exact symptom