HACS, el Home Assistant Community Store, es la puerta de entrada a una buena parte de las integraciones y tarjetas más interesantes que hemos usado en nuestra instalación a lo largo de los años: desde la iluminación circadiana que explicamos en nuestra guía de iluminación circadiana con Home Assistant hasta integraciones concretas de inversores solares o sistemas de riego. Precisamente por eso, cuando algo falla durante su instalación, la frustración es mayor de lo habitual: es la primera pieza que necesitas para acceder a buena parte del resto del ecosistema. Vamos a repasar, síntoma por síntoma, los problemas más habituales y su solución.
Síntoma: HACS no aparece como opción al instalarlo
Si acabas de seguir el proceso de instalación de HACS y, al ir a añadir una nueva integración, no lo encuentras en el listado, lo primero que hay que comprobar es si el proceso de instalación llegó realmente a completarse del todo. HACS no se instala como un complemento tradicional desde la tienda de Home Assistant, sino que requiere una serie de pasos específicos: descargar los archivos mediante una línea de comandos mientras tienes acceso SSH o terminal al sistema, reiniciar Home Assistant por completo (no basta con recargar la configuración), y solo entonces añadir la integración desde el apartado correspondiente.
Si te has saltado el reinicio completo del sistema después de descargar los archivos, es la causa más probable de que HACS no aparezca todavía como opción disponible. Un reinicio completo, no una simple recarga de automatizaciones o de YAML, suele resolver este síntoma concreto.
Síntoma: error de autenticación con GitHub durante la configuración
Una vez que HACS sí aparece como integración y empiezas el proceso de configuración, es habitual que te pida vincular una cuenta de GitHub mediante un código de activación. Si este paso falla, lo más común es que el código haya caducado antes de que llegaras a introducirlo en la web de GitHub (el margen de tiempo suele ser limitado), o que hayas iniciado sesión con una cuenta de GitHub distinta a la que esperabas usar, generando una autorización que no coincide con lo que Home Assistant está esperando recibir.
La solución más fiable es cancelar el proceso de configuración por completo, eliminar la integración si ya se había creado de forma incompleta, y empezar de nuevo desde cero, prestando atención a completar el proceso de autorización en GitHub en los primeros minutos tras generarse el código, sin dejar la pestaña abierta mucho tiempo antes de introducirlo.
Síntoma: HACS desaparece después de una actualización importante de Home Assistant
Este es, probablemente, el síntoma que genera más confusión, porque da la sensación de que algo se ha roto sin motivo aparente. Home Assistant, al ser un proyecto en desarrollo muy activo, introduce de vez en cuando cambios en su arquitectura interna que pueden dejar temporalmente desactualizadas ciertas integraciones de terceros, incluido HACS, hasta que el propio proyecto HACS publica una actualización compatible con la nueva versión.
Antes de hacer cualquier cambio drástico, comprueba si existe una versión más reciente de HACS disponible, ya que es habitual que, tras una actualización mayor de Home Assistant, el equipo de HACS publique una nueva versión compatible en cuestión de días. Si acabas de actualizar Home Assistant a una versión recién salida y HACS deja de funcionar, en bastantes casos la solución más sencilla es, simplemente, tener un poco de paciencia y esperar a la actualización correspondiente, en lugar de intentar forzar una reinstalación completa que, en este escenario concreto, no suele solucionar nada.
Síntoma: las integraciones instaladas desde HACS no aparecen en Home Assistant
A veces HACS en sí mismo funciona perfectamente, pero una integración concreta que has instalado a través de él no aparece disponible al intentar añadirla desde el apartado de integraciones de Home Assistant. Esto suele deberse a que, igual que ocurre con la instalación inicial de HACS, instalar una integración nueva a través de HACS requiere un reinicio completo del sistema antes de que esa integración quede disponible para añadirse, un paso que es fácil pasar por alto si estás acostumbrado a que otros cambios de configuración no lo requieran.
Si ya has reiniciado y la integración sigue sin aparecer, el siguiente paso es revisar el registro de errores del sistema, accesible desde Ajustes > Sistema > Registros, buscando cualquier mensaje relacionado con el nombre específico de esa integración. Es relativamente habitual que una integración de la comunidad, mantenida por un desarrollador individual en su tiempo libre, no se actualice con la misma rapidez que el propio Home Assistant, generando errores de compatibilidad temporales tras ciertas actualizaciones del sistema.
Síntoma: HACS funciona, pero algunas integraciones de terceros muestran errores constantes
Si HACS en sí mismo está perfectamente operativo, pero una integración concreta instalada a través de él genera errores de forma recurrente en el registro del sistema, conviene distinguir entre un problema de la propia integración (que requeriría reportarlo al desarrollador correspondiente, normalmente a través de su repositorio) y un problema de configuración por tu parte. Revisar la documentación específica de esa integración, normalmente enlazada desde su propia ficha dentro de HACS, suele aclarar si el error que estás viendo es un problema conocido con una solución documentada, o algo que requiere reportar directamente.
Una recomendación general: no instales HACS «por si acaso»
Un consejo que damos siempre a quien empieza con Home Assistant: instala HACS cuando realmente necesites una integración o recurso concreto que no está disponible de forma nativa, no como un paso «obligatorio» nada más terminar la instalación inicial, tal y como explicamos en nuestra guía de instalación de Home Assistant OS. Cada integración de terceros que añades es, también, una pieza adicional que puede fallar o quedar desactualizada con el tiempo, así que merece la pena instalar solo lo que realmente vayas a usar, revisando periódicamente qué integraciones de HACS siguen aportando valor a tu instalación y cuáles podrías eliminar con el tiempo.
Qué hacer si ninguna de estas soluciones funciona
Si después de revisar todos estos síntomas el problema persiste, el siguiente paso recomendado es acudir directamente a la documentación oficial del proyecto HACS, disponible en hacs.xyz, donde se mantiene actualizada la guía de instalación oficial y una sección específica de solución de problemas frecuentes, más detallada y actualizada que cualquier guía general como esta, precisamente porque la mantiene el propio equipo del proyecto. Si tras consultarla el problema sigue sin resolverse, el foro comunitario de Home Assistant en community.home-assistant.io suele tener hilos activos sobre problemas recientes de compatibilidad entre HACS y las últimas versiones de Home Assistant, donde otros usuarios suelen compartir soluciones a problemas muy recientes antes incluso de que lleguen a documentarse oficialmente.
Conclusión
La mayoría de problemas con HACS no tienen que ver con una instalación mal hecha desde el principio, sino con pasos intermedios —reinicios completos, tiempos de autorización con GitHub, actualizaciones recientes de Home Assistant— que son fáciles de pasar por alto si no sabes exactamente qué buscar. Siguiendo el síntoma concreto que estás experimentando, en lugar de reinstalar todo desde cero a la primera de cambio, la solución suele estar mucho más cerca de lo que parece al principio.