Troubleshooting guide

Zigbee2MQTT Coordinator Not Found: Fix the USB Adapter Startup Error

Category: Smart Home

You started Zigbee2MQTT with a USB coordinator and a new Zigbee device to pair, but startup stops at the coordinator step with a not-found error.

Confirm the coordinator is visible to the host

Unplug and replug the USB coordinator, then list serial devices on the host. On Linux, run ls -l /dev/serial/by-id/. You should see an entry containing the adapter’s vendor name, such as usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus.... If the directory is empty or the entry disappears after replugging, the problem is physical: try another USB port, a powered hub, or a different cable. A missing by-id entry means Zigbee2MQTT has nothing to open.

Check the configured port and permissions

Open your Zigbee2MQTT configuration.yaml and inspect the serial section. The port value must match the by-id path exactly, including case. Avoid /dev/ttyUSB0 because it can change between reboots. Then confirm your user is in the dialout group on Linux; run groups and look for dialout. If it is absent, add the user and log out and back in. A permission denial often surfaces as a generic open failure.

Verification test

Stop Zigbee2MQTT, then run a direct read test: cat /dev/serial/by-id/<your-adapter>. It will emit binary noise; press Ctrl+C. If the command returns permission denied or no such file, the coordinator is still not reachable. Restart Zigbee2MQTT and watch the log. A healthy start shows the adapter opening and the coordinator firmware version. If it still reports zigbee2mqtt coordinator not found, the path or device is still wrong.

Rollback and recovery

Before editing, copy configuration.yaml to configuration.yaml.bak. If a change makes startup worse, restore the backup and replug the adapter. If the by-id entry never appears on any port, the adapter may have failed; test it on another host before replacing it. For guided diagnosis,

Zigbee2MQTT dashboard showing a paired device and MQTT state

Ask for help.


Back to the service page · Ask about this exact symptom