Troubleshooting guide
Zigbee2MQTT Pairing Fails: Coordinator, Permit-Join, Device, Logs
Category: Smart Home
zigbee2mqtt pairing failed.
Zigbee pairing failures are usually coordinator, permit-join, device reset, or MQTT state. Test one device and read the interview log instead of retrying blindly.
Before you start
- Zigbee2MQTT with a supported coordinator
- One Zigbee device and its reset procedure
- Access to the Zigbee2MQTT log and MQTT broker
- The device close to the coordinator
Step-by-step checks
Step 1: Confirm the coordinator is online
Open Zigbee2MQTT settings/log and verify the serial adapter is detected with a stable path. Check the coordinator firmware and recent errors.
Check: The log shows the coordinator started and no serial error is repeating.
Step 2: Open permit join and watch the log
Enable permit join for a limited time, then put the device in pairing mode. Follow the interview messages in the log rather than only watching the device list.
Check: The log shows the device joining or a specific interview error.
Step 3: Reset the device correctly
Follow the manufacturer's exact reset/pairing sequence. Keep the device close, remove it from any previous hub, and avoid repeating the reset during the interview.
Check: The device emits its pairing indication and the interview starts.
Step 4: Finish the interview and test control
Wait for the interview to complete, then toggle the device and read its state in Zigbee2MQTT. Check the MQTT topic/entity in Home Assistant.
Check: Commands work and state updates in the UI.
Step 5: Restart and repeat
Restart Zigbee2MQTT, wait for the coordinator, and test the same device again. Confirm it is not marked offline.
Check: Control and state survive the restart.
Verify the result
The device pairs, responds to a control command, reports state, and remains available after a Zigbee2MQTT restart.
Rollback
Remove only the test device if pairing is wrong. Keep the coordinator configuration and existing devices unchanged.
Ask for help with this exact symptom · All troubleshooting guides