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


Back to the service page · Ask about this exact symptom