Zigbee2MQTT · Troubleshooting · Backstage

Tu dispositivo Zigbee está emparejado pero no aparece en Home Assistant: diagnóstico completo

Última revisión: 18/11/2026 · Zigbee2MQTT 2.14.3 · Home Assistant 2026.11

Coordinador Zigbee USB y relé doméstico sobre una mesa de taller, diagnosticando un dispositivo que no aparece en Home Assistant

El punto de falla no está en el emparejado: casi siempre está entre Zigbee2MQTT y el broker MQTT.

Si el dispositivo aparece en la interfaz de Zigbee2MQTT pero no en Home Assistant, el problema está casi siempre en el puente entre ambos: o Zigbee2MQTT no está conectado al broker MQTT, o no tiene activada la integración con Home Assistant. Esta guía recorre las causas en orden, de la más común a la más rara, con el YAML exacto que hay que revisar.

No es magia ni sincronización instantánea. El flujo es: Zigbee2MQTT recibe el evento del dispositivo, lo publica como topic MQTT en el broker, y Home Assistant se suscribe a ese broker y reconstruye la entidad. Si cualquiera de los dos lados del puente está mal configurado, el dispositivo se queda viviendo solo dentro de Zigbee2MQTT y nunca llega a Home Assistant. Esta pieza es el backstage de ese fallo, documentado a partir de hilos reales de Reddit y de la guía de instalación de Aguacatec, no de un panel que ya funciona.

El diagnóstico en una tabla

Empezá por la fila que se parezca a lo que ves. Luego saltás a la sección concreta.

Tabla de diagnóstico: dispositivo Zigbee emparejado pero invisible en Home Assistant.
Lo que ves Causa probable Qué revisar
No aparece ni en Zigbee2MQTT La inclusión no terminó o el interview quedó incompleto. Activá permit_join, acercá el dispositivo y repetí el emparejado.
Aparece en Zigbee2MQTT, pero nada llega a Home Assistant Zigbee2MQTT no está conectado al broker MQTT. Mirá el estado de MQTT en Z2M, el servidor y las credenciales.
Aparece en Z2M y hay datos MQTT, pero no aparece la entidad Descubrimiento desactivado en Z2M o en Home Assistant. homeassistant: true y mqtt: discovery: true.
La entidad existe pero no se ve en el panel Entidad deshabilitada por defecto. Ajustes > Entidades: buscá y activá la entidad.
Aparece y se va, queda "no disponible" Red Zigbee débil o coordinador con firmware problemático. Revisá LQI/rutas y el firmware del coordinador.

Causa 1: Zigbee2MQTT no conecta con el broker MQTT

Es la más habitual y la más silenciosa. Zigbee2MQTT puede estar emparejando y mostrando dispositivos en su propia interfaz mientras el proceso no consigue autenticarse contra el broker. El resultado: los dispositivos "existen" en Z2M pero jamás se publican hacia Home Assistant.

La señal está en el registro de Zigbee2MQTT: líneas de error de conexión o un estado que no llega a connected. Revisalo en bitácora dentro del complemento. Si el broker exige usuario y contraseña y están mal, no hay mensaje amable: simplemente no fluye nada.

El bloque de configuración que hay que contrastar contra la instalación real:

configuration.yaml — Zigbee2MQTT
mqtt:
  server: mqtt://127.0.0.1:1883
  user: mqtt-user
  password: mqtt-password

homeassistant: true

permit_join: false

127.0.0.1 solo sirve si el broker MQTT corre en la misma máquina que Zigbee2MQTT. Si usás el complemento, el broker normalmente es el servicio MQTT de Home Assistant y la dirección puede ser distinta; el punto es que coincida con la que escucha el broker. La clave homeassistant: true habilita el descubrimiento de entidades. Sin ella, o con false, los dispositivos siguen en Zigbee2MQTT y Home Assistant no se entera de nada. Está documentado en hilos de Reddit como la causa clásica de este problema.

Fuente: hilo resuelto Zigbee devices not showing in HA (solved) y guía de Aguacatec.

Causa 2: Home Assistant no está descubriendo los topics MQTT

Zigbee2MQTT está bien conectado, pero Home Assistant no transforma los topics MQTT en entidades. Eso pasa cuando la integración MQTT no está configurada, o está configurada con el descubrimiento apagado. En Home Assistant, la integración MQTT escucha el broker y, gracias al prefijo de descubrimiento, crea la entidad correspondiente.

configuration.yaml — Home Assistant
mqtt:
  discovery: true
  discovery_prefix: homeassistant

Si usás el complemento MQTT oficial de Home Assistant, no suele faltar. El problema aparece sobre todo en montajes manuales, cuando alguien instala Mosquitto aparte y se olvida de configurar la integración MQTT dentro de Home Assistant. Verificá en Ajustes > Dispositivos y servicios que exista una integración MQTT conectada, no solo el broker corriendo por su cuenta.

Causa 3: la inclusión no terminó bien

Si el dispositivo no aparece ni en la interfaz de Zigbee2MQTT, el fallo es anterior a todo lo demás: el emparejado no terminó. Lo típico es que el dispositivo entró en modo vinculación, Z2M lo vio a medias y el interview quedó incompleto. En Zigbee2MQTT eso se ve como un dispositivo con nombre genérico, sin fabricante, o con estado de entrevista fallido.

La corrección no tiene YAML glamuroso: activá el modo de unión en la interfaz de Z2M, acercá el dispositivo al coordinador para descartar alcance, y repetí. No avances al siguiente problema hasta que el dispositivo se vea completo en Z2M con sus entidades declaradas. Sin eso, todo lo anterior es ruido.

Causa 4: la entidad existe pero está deshabilitada

Un caso traicionero. Home Assistant crea la entidad, pero no aparece en el panel porque viene deshabilitada por defecto o porque un cambio de versión la dejó desactivada. La búsqueda rápida es Ajustes > Dispositivos y servicios > Entidades: allí se listan también las deshabilitadas. Si aparece bajo el dominio correcto pero apagada, una pulsación en activar la devuelve al panel.

En la beta de una versión reciente de Zigbee2MQTT se documentó un cambio así: varias entidades de sensores de acción quedaron deshabilitadas por defecto. Si emparejás un dispositivo con este tipo de entidad y no la ves, el panel de entidades deshabilitadas es el primer lugar donde mirar.

Causa 5: red inestable que hace ir y venir el dispositivo

El síntoma "está y no está" no se arregla tocando YAML; se arregla mirando la salud de la malla. Home Assistant muestra no disponible cuando el dispositivo deja de responder. Las causas típicas son distancia, interferencias en el canal, un router Zigbee que se quedó fuera de la red, o un coordinador con firmware antiguo. Si ya tenés varios dispositivos y solo uno falla, movelo temporalmente cerca del coordinador y observá si se estabiliza: eso separa problema de hardware del problema de topología.

Para entender mejor cuál redireccionar a qué pieza, esta guía convive con las demás del clúster: Zigbee2MQTT vs ZHA en 2026, availability, timeout y payload retained y migrar el coordinador sin rehacer la red.

Árbol de decisión para no saltarte pasos

Árbol de decisión para diagnosticar un dispositivo Zigbee que no aparece en Home Assistant ¿Aparece en Zigbee2MQTT? no sí Repetí la inclusión: permit_join, acercá el dispositivo, revisá interview. ¿MQTT conectado en Z2M? no sí Revisá broker: servidor, usuario, contraseña y que MQTT esté levantado. Activa homeassistant: true, MQTT discovery y buscá entidades deshabilitadas.
Árbol de decisión: empezás siempre por izquierda, de arriba hacia abajo.

El backstage: por qué este fallo no avisa

La gracia de este problema es que no rompe ninguna integración visible. Zigbee2MQTT muestra el dispositivo en su panel, Home Assistant se abre sin errores, y solo falta la entidad. Por eso los hilos de Reddit sobre esto terminan casi siempre en la misma respuesta: mirá el enable de la integración y mirá si el broker está conectado. Lo demás (coordinador, entrevista, distancias) es secundario hasta que no se descartan los dos primeros.

¿Te quedás con el siguiente YAML ya probado?

Cada domingo publico un YAML nuevo ya probado y aviso cuando una integración local se rompe tras actualizar. Nada de novedades: solo lo que podés copiar y el fallo que vino antes. Las plantillas vivas están en plantillas YAML.

Introduce un correo válido para poder avisarte.

Detalles concretos de la interfaz de Zigbee2MQTT (texto exacto de menús y mensajes de log) quedan sin confirmar a fecha de 18/11: los reproduzco por los hilos citados, no por una captura propia de mi instalación. El YAML principal es verificable contra la documentación del proyecto.

Última revisión y cambios

Última revisión: 18/11/2026

  • Publicación original: diagnóstico completo con tabla, árbol de decisión y YAML.