Zigbee · Zigbee2MQTT · MQTT
Zigbee2MQTT no conecta a MQTT: diagnóstico y YAML del servidor
Si Zigbee2MQTT arranca pero su interfaz dice unable to connect al servidor MQTT, el coordinador no es el problema: Zigbee2MQTT no está llegando al broker. Es la avería más disimulada, porque los dispositivos pueden llegar a emparejarse en la propia interfaz de Z2M y aún así no aparecer nunca en Home Assistant. Aquí está el diagnóstico en el orden en que yo lo hago, con el YAML que funcionó en cada instalación.
Lo que significa el error
Ese mensaje es la forma que tiene Zigbee2MQTT de decir que no puede abrir una conexión TCP con el servidor MQTT o que el broker rechazó las credenciales. No es un fallo de radio, ni de emparejado, ni de adaptador. Por eso conviene atacarlo primero: si MQTT no respira, todo lo demás es invisible para Home Assistant.
Primer minuto: ¿el broker responde?
Antes de tocar nada, descarta que Mosquitto esté caído o que las credenciales no coincidan. Si tienes el add-on de Mosquitto en Home Assistant OS, entra en su pestaña Configuración y confirma el usuario y la contraseña. No los inventes: son los que pusiste ahí, no los de Zigbee2MQTT.
# Dentro del contenedor de Mosquitto (HAOS), para ver si acepta conexiones:
mosquitto_sub -h localhost -t '$SYS/broker/uptime' -u mqtt-user -P TU_PASSWORD
# Si responde con un número de segundos, el broker está vivo.
# Si devuelve "Connection refused" o "Not authorised", sigue leyendo.
Configuración que funciona
La configuración de MQTT depende de dónde corra Zigbee2MQTT. En Home Assistant OS el servidor no es localhost: es el nombre del add-on de Mosquitto, core-mosquitto. En Docker, localhost apunta al propio contenedor y por eso falla si el broker está en otro contenedor.
| Instalación | server | user | Aviso |
|---|---|---|---|
| HAOS + add-on Mosquitto | mqtt://core-mosquitto:1883 |
mqtt-user |
El usuario se crea en la configuración del add-on, no en Z2M. |
| Docker en el mismo host | mqtt://mosquitto:1883 |
el que definas en mosquitto.conf |
Si no usas una red compartida, localhost aísla el contenedor. |
| Docker Compose | mqtt://mosquitto:1883 |
el del servicio | El nombre del servicio hace de DNS dentro de la red de Compose. |
| Bare metal / otra máquina | mqtt://192.168.1.50:1883 |
el del broker | Comprueba que Mosquitto escucha en 0.0.0.0, no solo en localhost. |
Este es el bloque que yo mantengo en HAOS, con el add-on de Mosquitto instalado y el usuario mqtt-user:
homeassistant: true
permit_join: false
mqtt:
base_topic: zigbee2mqtt
server: mqtt://core-mosquitto:1883
user: mqtt-user
password: TU_PASSWORD
keepalive: 60
serial:
port: /dev/serial/by-id/usb-...
adapter: zstack
frontend: true
Para Docker Compose, cambia el server por el nombre del servicio y deja el mismo esquema. No pongas el puerto del frontend en server: el frontend va por HTTP, no por MQTT.
No pierdas otra tarde persiguiendo un YAML roto
Cada domingo mando un YAML ya probado y el aviso cuando una integración local se rompe tras actualizar. Lo prometido existe: plantillas YAML.
El error de sangrado que lo rompe
El error más repetido en los foros no es de red: es YAML mal indentado o con comillas en los nombres de clave. Zigbee2MQTT lo reporta como YAMLException: bad indentation of a mapping entry y deja de arrancar. Compáralo antes de culpar al broker.
# MAL: comillas en los nombres de clave
"mqtt":
"server": "mqtt://core-mosquitto:1883"
"user": "mqtt-user"
"password": "TU_PASSWORD"
# BIEN: claves sin comillas, todo al mismo nivel
mqtt:
server: mqtt://core-mosquitto:1883
user: mqtt-user
password: TU_PASSWORD
Home Assistant no ve los dispositivos
Una vez que Z2M conecta, la pieza que falta suele ser homeassistant: true, que es la línea que activa el descubrimiento MQTT hacia Home Assistant. Sin ella, Z2M publica datos, pero HA no los recoge. Si tu caso es que el dispositivo ya aparece en Z2M y aun así no llega al inventario de HA, el diagnóstico es otro: lo cubrí en la guía de dispositivo Zigbee emparejado y no aparece en Home Assistant.
Cuándo descartar MQTT
Si Mosquitto responde, el YAML está limpio y aun así no hay conexión, mira el log de Zigbee2MQTT. Un ECONNREFUSED apunta al puerto o al host; un Not authorised apunta a usuario o contraseña; un ETIMEDOUT a firewall o a que Mosquitto no escucha fuera de localhost. El coordinador solo es sospechoso cuando el log de Z2M sí arranca y publica, pero los dispositivos no responden o no emparejan: eso se diagnostica aparte, en la guía de Zigbee2MQTT vs ZHA.
Suscríbete y deja de buscar el error por tu cuenta
Guardo en la newsletter los YAML nuevos y los avisos de integraciones rotas. Mira antes lo que ya es público: plantillas YAML.