Saltar a contenido

Failure mode: HACS / custom integration rota tras HA upgrade

Cuarta entrada del catálogo. HA libera una YYYY.M.0; alguna integration custom instalada vía HACS no se carga (deprecated API, breaking change en core). HA arranca pero con warnings; el feature de la integration desaparece. Recovery: rollback de la integration o de HA Core, según el caso.

Cómo se manifiesta

  • Tras un upgrade de HA Core, una integration custom deja de aparecer en Settings → Devices & Services.
  • HA logs muestran Setup of custom integration X failed o Integration X failed to import.
  • HACS UI marca la integration con icono de error o "incompatible".
  • Devices/entities asociadas a la integration entran en estado "unavailable".

Caso documentado

Patrón recurrente en releases mensuales de HA (YYYY.M.0). Especialmente común cuando: - HA core deprecates una API que la integration usa. - Integration es maintained part-time por una sola persona y el release de HA se anticipa. - Custom integration depende de una library externa que también cambia.

Específicamente reportado en gaps (postmortems community a ingerir formal): "HACS no longer starts in HA", "What the HACS? New custom components blocked".

Cómo se detecta proactivamente

  • Pre-upgrade: revisar la integration en su repo GitHub → ver si hay release-candidate o issues abiertos por la versión target de HA. Parte del ha-pre-update-checklist paso 2.
  • Post-upgrade: alert LogQL: 
    {job="homeassistant", level="ERROR"} |= "custom integration" |= "failed"
  • Gatus check: si la integration expone entities específicas, healthcheck contra ellas (ej. sensor.foo_status != "unavailable").

Cómo se recupera

Opción A — Wait for integration update (preferida)

  1. Disable la integration con problema (Settings → Devices & Services → Disable).
  2. Anotar el error específico.
  3. Reportar issue al repo de la integration con la versión de HA + error log.
  4. Esperar update. Mientras tanto, HA y otras integrations funcionan.

Opción B — Rollback de HA Core

Solo si la integration afectada es crítica:

  1. Restore full backup pre-upgrade (ha-rollback-procedure).
  2. Pin HA Core a la versión anterior hasta que la integration tenga release compatible.
  3. Subscribir notifications del repo para saber cuando hay update.

Opción C — Patch local de la integration (avanzado)

Si tenés conocimiento Python:

  1. Clone la integration al custom_components/ editable.
  2. Identificar la API deprecated y reemplazarla.
  3. Mantener fork mientras esperás el upstream fix.
  4. No recomendado para el setup "no tinkering" del usuario.

Cómo se previene

En el pre-upgrade checklist

  • Listar custom integrations instaladas: find /config/custom_components -name '__init__.py' -exec head -3 {} \;
  • Verificar compatibilidad para cada una contra HA target version.
  • Decidir antes del upgrade: ¿qué integrations son críticas? ¿cuáles puedo perder temporalmente?

Política a largo plazo

  • Minimizar dependencia de HACS: cada integration custom es debt. Si una integration nativa de HA cubre el 80% del use case, preferirla.
  • Auditoría quarterly (../sources/dan-malone-ai-patterns-ha multi-agent): identificar integrations que el agente Architecture Strategist marca como "alta dependencia, baja maintenance".
  • Sunset list: integrations a reemplazar cuando aparezca alternativa nativa.

Para el agente AI

  • Antes de aprobar un upgrade de HA Core, el agente:
  • Lista las custom integrations.
  • Hace fetch del README/releases del repo de cada una.
  • Verifica que la versión target de HA esté en el "supported" listed.
  • Si cualquier integration no tiene match confirmado, NO autoriza el upgrade — alerta al humano.

Lo que el agente AI hace (perímetro autónomo)

Acción ¿Autónomo?
Disable integration con error tras upgrade Sí (mes 3+, low risk)
Reportar issue al repo de la integration Sí vía template estandarizado
Rollback de HA Core No, pide approval
Patch local de la integration Nunca — fuera de scope
Bloquear upgrade si custom integration no compatible Sí desde mes 2

Relaciones

Abierto / gaps

  • Ingerir community thread "What the HACS? New custom components blocked" como source canónico de un caso.
  • Template estandarizado de issue para que el agente lo use.
  • Lista concreta de integrations custom del usuario actual (gap del inventario).