502 Bad Gateway Home Assistant: Solución Rápida [2026]

Actualizado el 24 de enero de 2026

Enfrentarse a un error 502 Bad Gateway en Home Assistant es una de las experiencias más frustrantes. De repente, tu panel de control, el cerebro de tu hogar inteligente, es inaccesible. Aunque el pánico inicial puede hacerte pensar que todo está perdido, como Ingeniero IoT con años de experiencia, puedo asegurarte que en la mayoría de los casos, este error es un síntoma con solución, no una catástrofe.

A diferencia de lo que se pensaba en años anteriores, donde se apuntaba a causas muy específicas, en 2026 sabemos que el «502» es un mensaje genérico. Esta guía definitiva te enseñará a diagnosticar la causa real y a solucionar el error 502 de Home Assistant de forma metódica y eficaz.

¿Qué Significa Realmente un Error 502 en Home Assistant?

Para entender el problema, debemos visualizar cómo accedemos a Home Assistant. Generalmente, no nos conectamos directamente al núcleo del sistema. Nuestra petición (desde el navegador o la app) pasa primero por un «intermediario» o «proxy». En muchas instalaciones, este rol lo cumple un Add-on como NGINX Proxy Manager o el propio Supervisor de Home Assistant.

Un error 502 Bad Gateway significa simplemente esto: El proxy intentó comunicarse con el núcleo de Home Assistant, pero no recibió una respuesta válida.

Imagina que el proxy es un recepcionista de hotel. Tú le pides la llave de tu habitación (acceder a la interfaz), pero cuando el recepcionista llama a la habitación (al núcleo de HA), nadie contesta o la línea está cortada. El recepcionista vuelve y te dice «Lo siento, no puedo contactar con la habitación». Eso es un 502. El problema no es el recepcionista (el proxy), sino lo que ocurre dentro de la habitación (el núcleo de HA).

Causas Comunes del Error 502 Bad Gateway en 2026

He consolidado las causas más frecuentes que he visto en el campo en la siguiente tabla. Identificar tus síntomas aquí es el primer paso para encontrar la solución correcta.

Guía de Diagnóstico Paso a Paso: Cómo Revisar los Logs sin UI

Cuando Home Assistant no funciona, la interfaz gráfica no es una opción. Necesitamos acceder a los registros del sistema para ver el mensaje de error real. Esta es la clave para un diagnóstico certero.

Paso 1: Intenta el Acceso por IP Local

Antes de nada, abre tu navegador y prueba a acceder usando la IP local de tu dispositivo Home Assistant, seguida del puerto 8123. Por ejemplo: http://192.168.1.50:8123 o http://homeassistant.local:8123.

• Si funciona: ¡Buenas noticias! El núcleo de Home Assistant está vivo. El problema casi con total seguridad es un error del proxy inverso. Salta directamente a la solución 1.
• Si no funciona: El núcleo de Home Assistant no está respondiendo. Debemos revisar los logs para saber por qué. Pasa al siguiente paso.

Paso 2: Acceder a los Logs desde la Línea de Comandos (CLI)

La forma más fiable de revisar los logs de Home Assistant es a través de su interfaz de línea de comandos (CLI). Hay dos maneras principales de acceder:

1. Conexión SSH: Si tienes el Add-on «Terminal & SSH» instalado, puedes conectarte desde otro ordenador usando una aplicación como PuTTY (en Windows) o la terminal (en macOS/Linux).
2. Acceso Físico (Recomendado si SSH falla): Conecta un teclado y un monitor directamente a tu dispositivo (Raspberry Pi, NUC, etc.). Verás una consola de texto. Escribe login y pulsa Enter.

Una vez dentro de la CLI, estos son los comandos que te darán la verdad:

Para ver los logs del núcleo de Home Assistant:

ha core logs

Para ver los logs del Supervisor, que gestiona las actualizaciones y los Add-ons:

ha supervisor logs

Y para ver los logs de un Add-on específico (por ejemplo, NGINX):

ha addons logs a0d7b954_nginxproxymanager

Busca en la salida de estos comandos líneas que empiecen con ERROR o CRITICAL. Esos mensajes te dirán exactamente qué componente está fallando.

Soluciones Específicas para Cada Problema

Con la información de los logs, ahora podemos aplicar la solución correcta.

Solución 1: Corregir un Error de Proxy Inverso

Si podías acceder por IP, el problema está en tu proxy (ej. NGINX Proxy Manager).

– Revisa la IP: Asegúrate de que la IP de destino en la configuración de tu proxy coincide con la IP actual de Home Assistant. Si tu router asignó una nueva IP, la conexión se romperá. Considera reservar una dirección IP para Home Assistant.

– Verifica los Logs del Add-on: Usa el comando ha addons logs para ver si el proxy registra algún error.

– Configuración configuration.yaml: Revisa que en tu archivo configuration.yaml, dentro de la sección http:, tengas correctamente configurados los `trusted_proxies`.

Solución 2: Recuperarse de una Actualización Fallida

Una actualización fallida de Home Assistant es una causa muy común. Los logs suelen mostrar errores durante el inicio de un componente. La solución más rápida y segura es restaurar una copia de seguridad.

Desde la CLI, primero lista tus copias de seguridad disponibles:

ha backups

Copia el «slug» (el identificador único) de la copia más reciente y ejecútala con el comando de restauración:

ha backups restore slug_de_tu_copia_de_seguridad

El sistema se reiniciará y volverá al estado anterior. Para el futuro, te recomiendo encarecidamente automatizar tus copias de seguridad. Puedes aprender a hacerlo en mi guía para integrar Google Drive con Home Assistant. Si la restauración no funciona, mi guía sobre cómo hacer un downgrade en Home Assistant te ofrece métodos alternativos.

Solución 3: Liberar Recursos del Sistema

Si los logs muestran errores de «timeout» o el sistema se vuelve inaccesible bajo carga, es posible que tu hardware esté al límite.

– Reinicia el host: Un reinicio completo puede solucionar problemas temporales de memoria. Desde la CLI: ha host reboot.

– Desactiva Add-ons pesados: Add-ons como InfluxDB, Grafana o algunos que procesan vídeo pueden consumir muchos recursos. Desactívalos temporalmente desde la CLI para ver si el sistema se estabiliza: ha addons stop slug_del_addon.

Solución 4: Reparar una Base de Datos Corrupta

Si los logs apuntan claramente a un error de «recorder» o «malformed database», el archivo de historial está dañado. La solución es drástica pero efectiva (implica perder el historial de entidades):

1. Detén el núcleo de Home Assistant: ha core stop
2. Accede a tus archivos de configuración (vía Samba o desde la terminal) y busca el archivo home-assistant_v2.db en la carpeta /config.
3. Renómbralo a home-assistant_v2.db.old.
4. Inicia de nuevo el núcleo: ha core start

Home Assistant creará una nueva base de datos vacía y debería arrancar sin problemas. Para evitar esto en el futuro, considera usar una base de datos más robusta como explico en mi tutorial sobre cómo instalar MariaDB en Home Assistant.

Solución 5: Arrancar en Modo Seguro para Aislar un Componente Roto

Si sospechas que una integración personalizada o un Add-on recién instalado es el culpable, el modo seguro es tu mejor aliado. Este modo inicia Home Assistant sin cargar ninguna integración personalizada.

Desde la CLI, ejecuta:

ha core start --safe-mode

Si Home Assistant arranca en modo seguro, el problema reside en tu carpeta custom_components. Deberás acceder a ella y eliminar o renombrar la carpeta del componente sospechoso para solucionar el conflicto.

Preguntas Frecuentes (FAQ) sobre el Error 502

¿Cómo puedo prevenir el error 502 en el futuro?

La prevención es la mejor estrategia. Mis recomendaciones clave son: 1) Configura copias de seguridad automáticas y externas. 2) Lee siempre las «Breaking Changes» (cambios importantes) en las notas de cada actualización antes de instalarla. 3) Asegúrate de que tu hardware (especialmente en Raspberry Pi) tiene suficiente potencia y una fuente de alimentación de calidad.

¿He perdido todos mis datos si recibo un 502?

No necesariamente. Es muy importante entender que tus configuraciones (configuration.yaml), automatizaciones, scripts y paneles de Lovelace están en archivos de texto que rara vez se ven afectados. El mayor riesgo de pérdida de datos es el historial de sensores si la base de datos se corrompe y no tienes una copia de seguridad.

Mi Home Assistant no funciona y no tengo acceso SSH ni físico, ¿qué hago?

Este es el escenario más complicado. La única opción es apagar el sistema, extraer el medio de almacenamiento (la tarjeta SD o el SSD) y conectarlo a otro ordenador con un lector adecuado. Desde allí, podrás acceder a la partición de datos (llamada `hassos-data` o similar) y navegar hasta la carpeta de configuración para rescatar tus archivos y leer el fichero `home-assistant.log` manualmente.