Troubleshooting guide

Zigbee2MQTT Message Not Published: Fix MQTT Connection Failures

Category: Smart Home

You’ve paired a new Zigbee device with your USB coordinator, but Zigbee2MQTT can’t publish to the broker and entities remain unavailable.

Check MQTT Broker Connectivity

First, verify the broker is reachable from the Zigbee2MQTT host. Run mosquitto_sub -h <broker_ip> -t '#' -v from the same machine. If you see no output or a connection refused error, the broker is down or blocked. Confirm the broker service is running and that port 1883 (or your configured port) is open. In Zigbee2MQTT’s configuration.yaml, check the mqtt section: server, user, and password must match the broker’s credentials exactly. A single typo here causes a zigbee2mqtt message not published failure.

Inspect Zigbee2MQTT Logs

Start Zigbee2MQTT with DEBUG=* or check the log output. Look for lines like MQTT publish failed or Connection refused. If you see Error: connect ECONNREFUSED, the broker address is wrong or the broker isn’t listening. If you see Not authorized, the username or password is incorrect. Correct the credentials in configuration.yaml and restart Zigbee2MQTT.

Verify with a Test Publish

After fixing credentials, publish a test message: mosquitto_pub -h <broker_ip> -t 'test' -m 'hello'. Then subscribe to zigbee2mqtt/# and trigger a device event (e.g., press a button). You should see a JSON payload. If not, recheck the base_topic setting in configuration.yaml—it must match the topic you’re subscribing to.

Rollback and Recovery

If changes break things, restore your previous configuration.yaml from backup and restart. If the issue persists,

Zigbee2MQTT dashboard showing a paired device and MQTT state

Ask for help with your logs and configuration details.

Final Check

Ensure the USB coordinator is connected and recognized (ls /dev/ttyACM*). A missing coordinator can also prevent publishing. Once broker connectivity and credentials are correct, messages should flow and entities become available.


Back to the service page · Ask about this exact symptom