Actualizar Zigbee2MQTT: Guía Fácil y Solución de Errores

Actualizado el 31 de enero de 2026

Mantener tu red Zigbee al día es fundamental, y Zigbee2MQTT es el corazón de muchas de nuestras instalaciones de domótica. Sin embargo, actualizarlo puede generar respeto, especialmente por el miedo a que algo deje de funcionar. Como Ingeniero IoT con años de experiencia, he pasado por innumerables actualizaciones y he aprendido que la clave no es tener suerte, sino seguir un proceso metódico. Este artículo ha sido completamente reescrito para convertirse en tu guía de referencia definitiva en 2026, asegurando que cada actualización sea un proceso controlado y sin sorpresas.

¿Por Qué es Crucial Actualizar Zigbee2MQTT Regularmente?

Puede ser tentador seguir con la mentalidad de «si funciona, no lo toques», pero en el mundo del IoT, esto es un riesgo. Mantener Zigbee2MQTT actualizado te ofrece beneficios clave:

Compatibilidad con Nuevos Dispositivos: El ecosistema Zigbee crece a diario. Las actualizaciones son la única forma de asegurar que ese nuevo sensor o bombilla que acabas de comprar sea compatible.
Parches de Seguridad: Protege tu red de vulnerabilidades. Cada nueva versión corrige fallos que podrían comprometer la seguridad de tu hogar.
Mejoras de Estabilidad y Rendimiento: Los desarrolladores optimizan constantemente el código para hacer tu red Zigbee más rápida, estable y con mejor gestión de la memoria.
Corrección de Errores (Bug Fixes): Soluciona esos pequeños problemas en Zigbee2MQTT que a veces nos encontramos con dispositivos específicos.

El Checklist Pre-Actualización: 3 Pasos que No Puedes Omitir

Antes de hacer clic en «Actualizar», dedicar cinco minutos a esta preparación te puede ahorrar horas de frustración. Esta es mi rutina personal:

1. Leer las Notas de la Versión (Changelog)

Es el paso más importante y el que más gente omite. Ve a la página de GitHub de Zigbee2MQTT y busca la nueva versión. Presta especial atención a la sección «Breaking Changes» (Cambios Rompedores). Aquí se te avisará si una configuración que usas va a ser eliminada o si el comportamiento de algún dispositivo ha cambiado drásticamente.

2. Realizar una Copia de Seguridad Completa

Un buen backup de Zigbee2MQTT es tu red de seguridad. Si algo sale catastróficamente mal, podrás volver al estado anterior en minutos.

En Home Assistant: Ve a Ajustes > Sistema > Copias de seguridad y crea una copia de seguridad completa. Asegúrate de que incluya la App de Zigbee2MQTT.
Mejora Pro: Automatiza tus copias de seguridad en la nube. Si no lo has hecho ya, te recomiendo seguir mi guía para integrar Google Drive en Home Assistant. Es un salvavidas.

3. Verificar el Firmware de tu Coordinador

A veces, las versiones más recientes de Zigbee2MQTT requieren un firmware más moderno en tu coordinador (dongle USB o Ethernet) para funcionar correctamente. Revisa las notas de la versión por si mencionan alguna recomendación. Si llevas años sin actualizarlo, este es un buen momento para considerarlo. Si usas un Sonoff, por ejemplo, aquí te explico cómo actualizar el firmware del ZBDongle-P/E.

Cómo Actualizar Zigbee2MQTT: Guía para Cada Plataforma

El proceso varía ligeramente dependiendo de cómo tengas instalado Zigbee2MQTT. Aquí cubrimos los escenarios más comunes.

Método 1: En Home Assistant OS (La Vía Fácil)

Si usas Zigbee2MQTT en Home Assistant como una App, el proceso es muy sencillo:

Navega a Ajustes > Apps (anteriormente conocidos como Add-ons).
Busca la App de Zigbee2MQTT. Si hay una actualización disponible, verás un botón para actualizar.
Haz clic en Actualizar y espera a que el proceso termine.

Una vez finalizado, ve a la pestaña «Registro» para revisar que todo haya arrancado sin errores.

Método 2: En una Instalación con Docker

Si gestionas tus contenedores manualmente, el proceso es igual de simple:

Detén tu contenedor actual:
```
docker stop zigbee2mqtt
```
Descarga la última imagen:
```
docker pull koenkk/zigbee2mqtt:latest
```
Elimina el contenedor antiguo y arranca el nuevo con los mismos parámetros de configuración (volúmenes, puertos, etc.) que usaste para crearlo inicialmente. Si usas Docker Compose, el proceso es aún más fácil con `docker-compose pull` y `docker-compose up -d`.

Método 3: En una Instalación Manual (Bare-Metal)

Para los que lo ejecutan directamente sobre el sistema operativo:

Detén el servicio de Zigbee2MQTT:
```
sudo systemctl stop zigbee2mqtt.service
```
Navega a la carpeta de instalación (normalmente /opt/zigbee2mqtt).
Ejecuta los comandos de actualización:
```
git pull
npm ci
```

Inicia el servicio de nuevo:

sudo systemctl start zigbee2mqtt.service

Revisa el estado para confirmar que ha arrancado bien:
```
sudo systemctl status zigbee2mqtt.service
```

Solución de Problemas Comunes Post-Actualización

¿Algo ha ido mal? No te preocupes. Aquí están los problemas de Zigbee2MQTT más comunes y cómo los soluciono yo.

1. Error: Zigbee2MQTT no arranca o se reinicia en bucle

Este es el error de Zigbee2MQTT más frecuente. La causa casi siempre está en los registros.

Revisa los registros: Es el primer sitio donde mirar. Te dirá exactamente qué está fallando.
Error de sintaxis en `configuration.yaml`: Un cambio en la nueva versión puede haber convertido una de tus configuraciones en obsoleta. Revisa el archivo con un validador de YAML.
Error al detectar el coordinador: A veces, tras una actualización del sistema operativo, la ruta del puerto USB cambia. La mejor práctica es usar siempre la ruta `by-id`, que es persistente. Revisa tu archivo zigbee2mqtt/configuration.yaml:
```
serial:
  port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_...-if00-port0
```
Si usas un coordinador Ethernet como el popular SMLIGHT SLZB-06, asegúrate de que su dirección IP no haya cambiado.

2. Un dispositivo específico ha dejado de funcionar o se comporta de forma extraña

No te apresures a re-emparejarlo. Prueba esto primero:

Fuerza la reconfiguración: En la interfaz web de Zigbee2MQTT, ve al dispositivo y busca un botón o opción para «Reconfigurar». Esto fuerza al dispositivo a obtener la nueva configuración del coordinador sin perder su identidad en la red.
Consulta la documentación oficial: Busca tu dispositivo en la web de Zigbee2MQTT. Es posible que un cambio en la actualización haya modificado el nombre de una entidad (ej. de `occupancy` a `presence`) o eliminado alguna.

3. Entidades desaparecidas o renombradas en Home Assistant

Esto suele ser un «Breaking Change» anunciado. Tus automatizaciones y dashboards pueden dejar de funcionar. La solución es manual pero sencilla: ve a Ajustes > Dispositivos y Servicios > Entidades, busca las nuevas entidades relacionadas con tu dispositivo y actualiza tus scripts y tarjetas con los nuevos nombres.

4. Si todo lo demás falla: Restaura la copia de seguridad

Si la situación es crítica y no tienes tiempo para investigar, es hora de usar tu red de seguridad. Restaura la copia de seguridad que creaste. Si el problema va más allá de Zigbee2MQTT, puedes consultar mi guía sobre cómo hacer un downgrade completo de Home Assistant.

Preguntas Frecuentes (FAQ) sobre la Actualización

¿Tengo que volver a emparejar todos mis dispositivos después de actualizar?: No, en el 99% de los casos no es necesario. La información de los dispositivos se guarda en la configuración. Solo en casos de una corrupción grave o un cambio de coordinador mayor sería necesario.
¿Con qué frecuencia debería actualizar Zigbee2MQTT?: Mi recomendación es no actualizar en cada pequeña revisión, a menos que solucione un problema que te afecte directamente. Es una buena práctica revisar las actualizaciones una vez al mes, leer las notas de la versión, y si trae mejoras de seguridad o soporte para dispositivos que te interesan, proceder con el checklist.
¿Qué hago si la actualización requiere una nueva versión del broker MQTT?: Si usas la App de Mosquitto Broker en Home Assistant, mantenla actualizada de la misma forma que Zigbee2MQTT. Si tu broker MQTT está en otro sistema, asegúrate de actualizarlo antes de proceder con Zigbee2MQTT. Aquí tienes una guía sobre el broker Mosquitto en Home Assistant.

Mi Opinión como Ingeniero

Después de gestionar cientos de dispositivos y sistemas, he llegado a la conclusión de que una actualización exitosa de Zigbee2MQTT se reduce a un 10% de conocimiento técnico y un 90% de preparación y disciplina. Leer las notas de la versión y hacer una copia de seguridad son los dos pilares que sostienen una red domótica estable a largo plazo. Esta guía te proporciona el mapa; seguirlo metódicamente te garantizará llegar a buen puerto en cada actualización, disfrutando de las últimas mejoras sin los dolores de cabeza. ¡Feliz domotización!