Diagnostics for a Zigbee device that will not connect to its coordinator

First identify the situation: the Zigbee device has never joined, used to work and disappeared, or will not join after removal. Each case needs a different response. Repeated button presses and premature deletion usually erase useful diagnostic clues.

Quick diagnostic table

Symptom Likely cause First check
no response to reset in the log the device did not enter pairing mode or its battery is low exact-model instructions, a known-good battery, and a test near the coordinator
interview starts and then fails weak link, sleeping battery device, or partial model support wake the device during interview, move it closer, and check its model page
device joins but a required property is missing a different revision or incomplete converter support model, manufacturer, and the actual exposes list
a working device becomes offline power, coverage, powered-router failure, or radio interference last message, battery, nearby routers, and coordinator placement
device will not return after removal it still remembers the old network factory reset, then a new permit join window

If the device has never joined

  1. Read the exact model from the enclosure and check it in the official Zigbee2MQTT device catalog. A similar shop name does not guarantee the same electronics.
  2. Install a known-good battery or verify mains power.
  3. Bring the device within 0.5–1 metre of the coordinator. First pairing at its final location in a distant greenhouse makes diagnosis harder.
  4. Enable permit join for a limited time. Zigbee2MQTT can also target a specific router for joining.
  5. Factory-reset the exact model according to its instructions. Pairing mode usually has a distinct flash pattern, not merely a lit LED.
  6. Read the log. A successful join reaches a completed interview, after which the model and capabilities appear.

The official sequence is documented under Allowing devices to join. If a battery device falls asleep during interview, wake it briefly with its normal button instead of factory-resetting it again.

If a working device disappeared

Do not delete it immediately. Preserve its friendly name, exact model, last message time, and power state, then check in order:

  1. Zigbee2MQTT itself is running and the coordinator still sees other devices;
  2. the missing device has power or a fresh battery;
  3. no powered smart plug or relay that routed its traffic was switched off;
  4. no Wi-Fi access point, SSD, USB 3.0 device, or other 2.4 GHz interference source was moved nearby;
  5. the device returns after one button wake-up or a brief power cycle.

linkquality is useful for comparison, but one number does not prove route quality. Repeatable messages at the final location matter more. Zigbee2MQTT recommends moving the USB coordinator away from the computer with a shielded extension cable and adding suitable powered routers where needed: improving range and stability.

If devices disappeared after a power outage

Separate a coordinator problem from powered-router and battery-device problems:

  1. confirm that Zigbee2MQTT started with the original data directory and network database;
  2. verify that the coordinator uses the expected USB port and bridge/state is online;
  3. restore power to smart plugs and relays that previously acted as mesh routers;
  4. allow routes to recover, then wake a battery sensor once with its normal button;
  5. compare last_seen across several devices — a whole branch disappearing together often points to one powered router;
  6. consider re-pairing only after power and logs have been checked.

Do not create a new Zigbee network or delete the data directory as a quick test. A changed network key can require every device to be paired again. On Windows, also check whether the COM port changed after reboot.

Reading availability correctly

When availability is enabled, Zigbee2MQTT publishes online or offline to the device availability topic. Powered devices and sleeping battery sensors use different timeouts: a battery sensor is not expected to report every ten minutes. An overly short custom timeout therefore creates false alarms.

Check the default behavior in the Device Availability documentation. For irrigation, also apply a separate freshness limit to the actual measurement. An old soil-moisture value is unsafe even if the device has not yet been marked offline.

After removing a device from the network

Deleting an entity in Zigbee2MQTT does not always reset the physical device. It may still remember the old network. Use this sequence:

  1. close the previous permit join window;
  2. factory-reset the device;
  3. open a new permit join window;
  4. keep the device near the coordinator until interview completes;
  5. verify real readings before moving it to the final location.

After moving it, wait for several normal report cycles. If the sensor disappears again only at its final location, pairing works and the likely problem is coverage or interference.

When not to use the device in an automation

Do not connect it to a pump, lighting, or ventilation rule if interview does not complete, a required property disappears, readings jump without a physical reason, or freshness is unknown. Establish stable monitoring first. The farm automation page shows how GrowerHub presents zones and stale data.

Final checklist

  • the exact model is supported;
  • power or battery is healthy;
  • factory reset followed the model instructions;
  • permit join was open only during connection;
  • interview completed;
  • actual exposes were verified;
  • messages remain stable at the final location;
  • stale data blocks dangerous automations.

Following this order reveals whether the failure is pairing, model support, or the working mesh. For a new network, start with the coordinator guide and sensor examples. GrowerHub can enable joining for three minutes and automatically shows devices that complete the interview.