Entidades huérfanas Home Assistant: guía con Spook

En mi día a día como creador de contenido y probador de hardware domótico, es normal que se acumulen entidades huérfanas en Home Assistant: sensores que ya no existen, IDs antiguos tras reemparejar Zigbee, dispositivos retirados, etc. Eso ensucia el sistema, dispara reparaciones y, a veces, rompe automatizaciones.
En este artículo te explico cómo detectarlas y limpiarlas con Spook de forma segura, paso a paso y sin cargarte tus automatizaciones.

Índice

Qué son las entidades huérfanas en Home Assistant

Son entradas del registro de entidades que ya no están asociadas a ninguna integración o dispositivo real. Suelen aparecer cuando:

Desinstalas una integración o eliminas un dispositivo.
Reemparejas un sensor Zigbee/Z2M y cambia su entity_id.
Cambias nombres en ESPHome y quedan restos antiguos.
Haces pruebas (como yo 😅) y luego quitas el hardware.

Diferencia clave:
No disponible (unavailable): la entidad existe, pero no responde.
No encontrada (not found): la entidad ya no existe y tus automatizaciones o tarjetas la siguen referenciando.

Panel de Reparaciones: tu primer radar

Antes de borrar nada, reviso Ajustes → Sistema → Reparaciones. Ahí veo:

Avisos tipo “Entidad referenciada desconocida” en automatizaciones/scripts.
Botón para Ignorar (útil para limpiar la vista mientras trabajo).
Opción de Mostrar reparaciones ignoradas para retomarlas después.

Esto no borra entidades; solo gestiona avisos.

Spook: la navaja suiza para entidades huérfanas Home Assistant

Spook (vía HACS) añade acciones y botones que facilitan el mantenimiento masivo:

Ignorar todas las reparaciones / Restaurar todas (limpieza visual, no destruye nada).
Listar entidades huérfanas de la base de datos.
Eliminar todas las entidades huérfanas (acción destructiva, úsala con cabeza).

Consejo honesto: antes de cualquier limpieza agresiva, haz backup.

Cómo detectar entidades huérfanas (sin borrar todavía)

Reinicia Home Assistant (Spook necesita un arranque para escanear bien).
Ve a Herramientas → Acciones y ejecuta:
- List all orphaned database entities (homeassistant.list_orphaned_database_entities).
Abre Ajustes → Registro del sistema y revisa el listado.
Opcional: crea un sensor de conteo (si Spook lo expone en tu instalación) o añade una card para tenerlo a la vista.

Si aparecen muchas, no te agobies. Es normal si pruebas hardware.

Cómo limpiar entidades huérfanas (con seguridad)

Método prudente (recomendado)

Guarda la lista detectada (fecha + listado).
Busca referencias en tus automatizaciones y tarjetas (reemplaza o elimina lo que apunte a entidades que ya no existen).
Vuelve a listar huérfanas para confirmar que ya no están en uso.

Método rápido (cuando ya estás seguro)

Ejecuta en Herramientas → Acciones:
- Delete all orphaned entities (homeassistant.delete_all_orphaned_entities).
Reinicia Home Assistant.

Esto no modifica tus archivos YAML. Si alguna automatización seguía usando una entidad borrada, verás “Entidad no encontrada” hasta que la corrijas.

Evita editar 20 automatizaciones: usa alias con sensores plantilla

Cuando sustituyo un dispositivo (por ejemplo, un Shelly EM por otro medidor), no quiero buscar y cambiar 20 entity_id. Prefiero crear un alias estable mediante un sensor plantilla y referenciar siempre ese alias en las automatizaciones.

Ejemplo (plantilla como alias)

template:
  - sensor:
      - name: "potencia_cocina_actual"
        unit_of_measurement: "W"
        state: "{{ states('sensor.nuevo_medidor_channel_2_power') }}"

Ahora mis automatizaciones usan sensor.potencia_cocina_actual.
Si cambio de hardware, solo ajusto la plantilla una vez. Así no toco automatizaciones.

Mapea y sustituye entity_id rápido (workflow real)

Identifica las entidades antiguas (ej.: sensor.shellyem_..._channel_2_power).
Instala el nuevo dispositivo y anota sus nuevas entidades.
En tu editor (VS Code), haz Buscar/Reemplazar por archivo o por carpeta:
- De → sensor.shellyem_98cdac1ea5a1_channel_2_power
- A → sensor.nuevo_medidor_channel_2_power
Guarda, recarga automatizaciones y prueba.
Cuando todo funcione, limpia entidades huérfanas con Spook.

Buenas prácticas si pruebas mucho hardware (como yo)

Usa un prefijo para dispositivos de demo (p. ej., ztest_, demo_).
Crea áreas específicas para pruebas y muévelas allí (luego es más fácil filtrar y limpiar).
Mantén nombres estables para alias (plantillas) y evita depender del entity_id “crudo”.
Tras cada review, elimina el dispositivo desde Dispositivos y servicios (no solo lo desconectes).
Agenda una revisión mensual: listar huérfanas, revisar reparaciones y hacer backup.

Errores típicos (y cómo los resuelvo)

“Entidad no encontrada” en una tarjeta Lovelace → esa tarjeta aún apunta a una entidad borrada. Edito la tarjeta y sustituyo la entidad o la elimino.
Automatización que no se dispara → tenía una condición basada en un sensor antiguo. Sustituyo por el alias o por la nueva entidad.
Zigbee reemparejado que cambió ID → reetiqueto con el nombre deseado y borro las entidades huérfanas del emparejado anterior.

FAQ rápida sobre entidades huérfanas Home Assistant

¿Ignorar reparaciones borra entidades?
No. “Ignorar” solo oculta avisos.

¿Eliminar huérfanas modifica mis automatizaciones?
No. Los YAML no se tocan. Si una automatización sigue referenciando algo borrado, verás el aviso y tendrás que editarla.

¿Cómo sé si es “no disponible” o “no encontrada”?
En Estados: unavailable = existe pero no responde; not found = ya no está en el sistema.

¿Qué pasa si borro “a lo bruto”?
Nada se rompe físicamente, pero verás más avisos de “entidad no encontrada” en automatizaciones/paneles que aún las usaban. Por eso recomiendo alias + búsqueda antes de limpiar.

Conclusión

Las entidades huérfanas en Home Assistant son normales si pruebas dispositivos como yo. La clave es tener método:

Detectarlas con Spook,
Sustituir referencias en automatizaciones mediante alias plantilla,
Y limpiar cuando ya no las necesitas.

En el vídeo complementario muestro este proceso en vivo, con ejemplos reales y el flujo exacto que sigo para no dejar cabos sueltos.