When a new Zigbee sensor, plug, or switch will not appear in Home Assistant, the cause is usually pairing mode, coordinator connectivity, radio interference, or device compatibility. Work through these checks in order and avoid resetting your entire Zigbee network as a first step.
1. Confirm which Zigbee integration is running
Open Settings → Devices & services and identify whether your network is managed by Zigbee Home Automation (ZHA) or Zigbee2MQTT. Confirm the integration is loaded and its coordinator is available. A device cannot join if the coordinator or add-on is stopped, disconnected, or pointing to the wrong serial device.
Use one Zigbee network for pairing. Do not try to join the same device through ZHA and Zigbee2MQTT simultaneously; they manage separate networks and coordinators.
2. Start discovery before activating pairing
Open the integration’s add-device flow first, then put the device into pairing mode exactly as the manufacturer specifies. Some devices advertise for only a short time. A battery device may need its button held or tapped in a specific sequence; avoid guessing, because reset patterns vary by model.
3. Pair close to the coordinator
For initial setup, place the device a few feet from the coordinator if practical. If the coordinator is a USB stick, use a USB extension cable to move it away from the computer, USB 3 ports, external drives, and Wi-Fi access point. Metal cabinets and dense walls can weaken radio communication.
If close pairing works but the device fails in its final location, investigate coverage and mesh routing rather than repeating factory resets.
4. Check compatibility and firmware
Search the official ZHA device database or Zigbee2MQTT supported-device list for the exact model and hardware revision. Some devices need newer integration versions or specific firmware, and some expose only part of their features. Confirm the device uses Zigbee rather than Wi-Fi, Bluetooth, or Thread; similar-looking products can use different protocols.
5. Read the logs before retrying
Look at the integration logs at the time of the failed join. A timeout suggests a different problem from a serial-port error or an unsupported-device message. If the coordinator itself is unavailable, solve that first; repeated device resets will not fix a disconnected radio.
6. Retry safely
- Confirm the coordinator is online.
- Enable permit-join or start the add-device flow.
- Reset only the target device using its manual.
- Pair near the coordinator and wait for discovery to finish.
- Move the device to its intended location and check signal quality.
Delete a stale device entry only after confirming it belongs to the device you are repairing. Do not erase coordinator data or rebuild the network unless logs and backups support that decision.
If it still will not pair
Record the exact model, integration (ZHA or Zigbee2MQTT), coordinator model and firmware, Home Assistant version, and the relevant log message. Those details are far more useful than a general “device not found” report and help narrow down compatibility, radio, or configuration problems. For related cases, see our ZHA pairing checklist and Zigbee2MQTT interview-failure guide.