Failure mode: HAOS update mechanism stuck

Si HAOS queda más de N versiones atrás (donde N parece ser grande pero no infinito), el mecanismo de update automático de la UI deja de ofrecer actualizaciones silenciosamente. El usuario queda varado sin señal clara de qué hacer. Recovery: forzar versión vía ha os update --version <X>.

Contexto

Esta es la primera entrada del catálogo de failure modes — gap media-prioridad abierto desde el scope del proyecto. Cada entrada del catálogo debe responder cuatro preguntas: cómo se manifiesta, cómo se detecta proactivamente, cómo se recupera, cómo se previene.

Contenido

Cómo se manifiesta

• HA OS y Core quedan en una versión antigua (mes(es) atrás del current).
• La UI no ofrece updates disponibles (Settings → System → Updates está vacío o muestra "no updates").
• "Show skipped updates" no persiste / no muestra nada útil.
• Warning sistemático "Unsupported system – Home Assistant OS version".
• En logs: 'StoreManager.reload' blocked from execution, unsupported OS version (u otros mensajes referenciando "unsupported OS").
• ha os update desde shell responde "already installed" aunque la versión es vieja.

Caso documentado

• Bob (rockandrollforall) — RPi 4 (aarch64), HAOS 10.5, HA Core 2025.8.3, Frontend 20250811.01.
• Quedó stuck 8 meses (agosto 2025 → abril 2026) sin saber cómo escapar.
• Ver ../sources/community-stuck-haos-april-2026.

Cómo se detecta proactivamente

Antes de que el usuario lo note: monitor periódico de versiones.

Heurísticas para alertar: 1. Tiempo desde último upgrade: si last_successful_update_at > 60 días, alertar. (No hay built-in todavía — Q5 gap.) 2. Gap de versión vs latest: query a home-assistant.io/manifest.json (o equivalente) y comparar contra ha core info. Si gap > 2 releases mensuales, alertar. 3. Warnings de "Unsupported system" en logs: regexp en Loki o LogCli. 4. Healthcheck integrado en el script de upgrade del agente (Q10): primer paso del pre-update checklist debe ser "verificar que la versión actual está en el rango supported para el hardware".

Cómo se recupera

1. Backup full primero (siempre).
2. Identificar el target intermedio. Para el caso de Bob: HAOS 10.5 → HAOS 17.2 saltó el gap; HA Core 2025.8.3 → 2026.4.1 después.
3. Forzar update HAOS con explicit version:

   ha os update --version <target_haos_version>
   

4. Esperar restart + verify.
5. Forzar HA Core a versión compatible con esa HAOS:

   ha core update --version <target_core_version>
   

6. Tras el restart, validar que la UI vuelve a ofrecer updates "automáticamente" para continuar el camino.
7. Aplicar luego el pre-update checklist estándar para cada release subsiguiente hasta llegar al current.

Cómo se previene

• Aplicar updates puntualmente (regla "esperar 7-10 días post release, pero no más"). Si pasan meses sin update, el riesgo de caer en este failure mode aumenta.
• Monitoreo proactivo (capa 1 de detección arriba).
• Documentar el último upgrade aplicado en el repo de configs — si pasan más de 60 días desde el último commit de upgrade, es señal.

Qué dice este caso sobre el wiki

• Valida la importancia del ha CLI con --version como tool — ya documentado en ../entities/ha-cli.
• Justifica la métrica "tiempo desde último upgrade aplicado" propuesta en ha-upgrade-reliability-strategy — la incorporamos formalmente.
• Cuestiona la idea de que "el sistema se actualiza solo": el built-in mechanism puede fallar silenciosamente. El humano (o un agente) debe verificar activamente.

Relaciones

• Failure mode catalogado (primera entrada): se va a ir poblando con cada postmortem nuevo.
• Recovery procedure usa: ../entities/ha-cli (ha os update --version).
• Detección proactiva apoya: Q5 observabilidad (alertas de "stale version").
• Prevención apoya: ha-upgrade-reliability-strategy (métrica "tiempo desde último upgrade").
• Caso fuente: ../sources/community-stuck-haos-april-2026.

Citas / evidencia

• "Hardware supported up to version 2026.4.1 for RPi4-64" — implícito en el thread: el hardware sí lo soportaba; el mecanismo de update fue el que falló.

• ha os update --version 17.2 (solución que funcionó) — ../sources/community-stuck-haos-april-2026.

Abierto / gaps

• Confirmar si hay un GitHub issue del HA team trackeando este failure mode (la UI no ofreciendo upgrade path en gaps grandes).
• Buscar otros postmortems del mismo tipo (Reddit, Discord) para validar la frecuencia.
• ¿Cuál es la "gap máxima" tolerada por la UI? Habría que probar empíricamente o encontrar la lógica en el code de HAOS.
• Definir el script de healthcheck que detecta este failure mode antes de que escale.