Cuando el YAML no funciona: encuentra el error sin probar cosas a ciegas

Este artículo puede contener enlaces de afiliado. Si compras desde estos enlaces, el precio para ti es el mismo y la tienda me paga una pequeña comisión que ayuda a mantener Tecnoyfoto.

Albert BarnosellEditor y responsable de Tecnoyfoto

← Capítulo 10 · Índice del curso

Una automatización puede fallar porque falta un espacio, porque una clave está en el lugar equivocado, porque la entidad no existe o porque la lógica impide llegar a la acción. Los cuatro problemas producen una sensación parecida —«no funciona»—, pero no se investigan con la misma herramienta.

En este capítulo construiremos un método de diagnóstico. No será una colección de mensajes de error para memorizar, porque esos mensajes cambian y ningún listado puede cubrir todas las combinaciones. Aprenderemos a localizar la capa del fallo, obtener pruebas y cambiar una sola cosa cada vez.

La secuencia será siempre:

observar → leer → clasificar → formular una hipótesis
         → cambiar una cosa → validar → reproducir → comprobar

Empieza describiendo el fallo con precisión

«La automatización no va» todavía no nos dice qué ha ocurrido. Antes de editar, responde preguntas observables:

• ¿Home Assistant acepta y carga la configuración?
• ¿La automatización aparece habilitada en la interfaz?
• ¿Se crea una traza cuando sucede el evento real?
• Si hay traza, ¿qué condición o acción detiene el recorrido?
• ¿La acción funciona cuando se prueba por separado?
• ¿Cuál era el estado real de las entidades en ese momento?
• ¿Qué esperabas y qué sucedió exactamente?

Estas preguntas dividen un problema grande. Si no aparece una traza, investigaremos primero el disparador o la carga de la automatización. Si la traza existe y termina en una condición falsa, no tiene sentido modificar la acción final.

Las cuatro capas de fallo

1. Sintaxis YAML

El documento no puede convertirse correctamente en listas, mapas y valores. Una tabulación, una comilla sin cerrar o una indentación que rompe la estructura pertenecen a esta capa.

data:
  title: "Curso YAML
  message: "La puerta está abierta"

La comilla de title no se cierra, de modo que el documento no puede analizarse como pretendíamos. Una indentación incorrecta también puede romper YAML o construir una estructura distinta. En esta capa nos ayudan el mensaje del analizador, la línea indicada y la comparación visual de niveles.

No corrijas automáticamente la línea que señala el error. A menudo el analizador detecta el problema en la línea donde la estructura ya resulta imposible, pero la causa real está justo antes: una comilla abierta, un corchete sin cerrar o una indentación incorrecta.

2. Esquema de Home Assistant

El YAML es válido, pero no representa una automatización válida. Este fragmento es YAML perfectamente legible:

actions: light.turn_on

Sin embargo, actions debe contener la secuencia con la forma que Home Assistant admite. El analizador YAML no conoce los conceptos triggers, conditions o actions; solo ve una clave y un texto. Es Home Assistant quien aplica su esquema y rechaza la estructura.

También pertenecen a esta capa una clave mal escrita, un campo obligatorio ausente o un valor de tipo incorrecto. La validación de configuración y los mensajes al recargar suelen ser las mejores pistas.

3. Referencia o ejecución

La automatización carga y empieza a ejecutarse, pero intenta utilizar algo que no está disponible o una acción devuelve un error:

- action: light.turn_on
  target:
    entity_id: light.course_livng_room

El error tipográfico en livng puede pasar la lectura de la estructura. El fallo aparece al resolver el objetivo o ejecutar la acción. Aquí consultaremos Estados, Acciones, la traza y los registros.

Una entidad en unavailable, una integración desconectada o un permiso insuficiente también pueden producir errores de ejecución sin que haya nada incorrecto en la indentación.

4. Lógica

Todo es válido y cada pieza podría funcionar, pero las decisiones no describen el comportamiento deseado:

triggers:
  - trigger: state
    entity_id: binary_sensor.course_front_door
    to: "on"
conditions:
  - condition: state
    entity_id: binary_sensor.course_front_door
    state: "off"

La automatización se dispara cuando la puerta pasa a abierta y, inmediatamente después, exige que esté cerrada. Podría darse una carrera extraña si el estado vuelve a cambiar enseguida, pero como diseño ordinario esa condición bloquea el camino que pretendíamos.

Ningún validador puede saber que querías encender la luz. Para Home Assistant, una condición falsa es un resultado legítimo, no un error. La lógica se diagnostica comparando requisitos, estados y recorrido real.

Valida antes de reiniciar

En Configuración → Herramientas → YAML, la sección de validación permite comprobar la configuración. Hazlo después de editar archivos manuales y antes de un reinicio.

La validación puede detectar problemas de sintaxis y muchos errores de esquema. No aplica los cambios y no demuestra que una entidad vaya a estar disponible mañana ni que la automatización tome la rama correcta.

Si el resultado señala una ruta como:

data['automation'][2]['actions'][0]['target']

léela como un itinerario:

1. Entra en automation.
2. Busca el tercer elemento de la lista: los índices empiezan en cero.
3. Entra en actions.
4. Mira la primera acción.
5. Revisa target.

No todos los mensajes muestran el nombre de archivo con la claridad deseada, especialmente cuando existen inclusiones. Utiliza el recorrido del capítulo anterior para saber qué archivo aportó esa parte de la estructura.

Recarga solo lo que has cambiado cuando sea posible

Después de una validación correcta, en la misma herramienta YAML pueden recargarse configuraciones concretas, como automatizaciones o scripts. Una recarga selectiva es más rápida y afecta menos a la casa que un reinicio completo.

No todo puede recargarse. Si la integración o sección no aparece entre las opciones disponibles, habrá que reiniciar Home Assistant. El orden seguro es:

1. Guardar el archivo.
2. Validar la configuración.
3. Recargar la sección si Home Assistant la ofrece.
4. Reiniciar solo cuando el tipo de cambio lo requiera.
5. Confirmar que la entidad o automatización está cargada.

Una validación correcta seguida de una recarga no equivale a una prueba funcional. Todavía debemos reproducir el caso.

Las trazas cuentan lo que ocurrió, no lo que creemos que ocurrió

Cada ejecución de una automatización genera un recorrido paso a paso. Desde el editor o la lista de automatizaciones podemos abrir Trazas y ver:

• Qué disparador inició la ejecución.
• Qué valores y variables estaban disponibles.
• Qué condiciones devolvieron verdadero o falso.
• Qué rama de choose fue seleccionada.
• Qué acciones se ejecutaron y cuánto tardaron.
• En qué paso apareció un error.

En automatizaciones escritas manualmente, asigna un id para que Home Assistant pueda almacenar sus trazas:

- id: "course_entry_light"
  alias: "Curso YAML - Luz de entrada"
  # resto de la automatización

No confundas Ejecutar acciones con provocar el disparador real. Ese botón omite los disparadores y las condiciones superiores. Sirve para comprobar la secuencia, pero no puede demostrar que un trigger ID o una variable trigger funcionen. Para esos casos reproduce el cambio real o usa una prueba controlada que proporcione el contexto necesario.

Una traza sin errores puede revelar igualmente el problema: quizá se recorrió default porque ninguna opción de choose coincidió, o una condición devolvió falso con un estado distinto del que imaginábamos.

Comprueba estados y acciones por separado

En Configuración → Herramientas → Estados, busca las entidades implicadas. Copia sus identificadores exactos y observa el estado real, no el texto amable que muestra una tarjeta del panel.

Recuerda que modificar un estado desde esta herramienta cambia temporalmente la representación interna. No controla el dispositivo físico. Es útil para simular una entrada y puede disparar automatizaciones, pero el dispositivo o su integración pueden sobrescribir el valor después.

En Acciones, ejecuta la acción mínima:

action: light.turn_on
target:
  entity_id: light.course_living_room

Si esto falla, el problema no está en el disparador de la automatización. Revisa entidad, integración, disponibilidad y datos de la acción. Si funciona, vuelve a la traza y busca qué impidió llegar a ella.

Prueba plantillas con sus valores difíciles

El editor de plantillas muestra el resultado en tiempo real. No pruebes solamente el caso cómodo. Para una temperatura, comprueba un valor por encima del umbral, otro por debajo y la situación unknown o unavailable.

{% set entity = 'sensor.course_living_room_temperature' %}
{{ has_value(entity) and states(entity) | float < 25 }}

El editor no reproduce automáticamente el contexto de una automatización. Variables como trigger o this solo existen en los lugares apropiados. Si una plantilla depende de trigger.to_state, podemos probar primero su parte independiente o definir datos simulados con cuidado, pero la verificación final debe hacerse en una ejecución real.

Lee los registros después de reproducir el problema

Los registros son más útiles cuando sabemos a qué hora se reprodujo el fallo y qué componente estaba implicado. Busca el mensaje más próximo a esa prueba, lee también las líneas relacionadas y conserva el error exacto.

No actives registro de depuración global durante días «por si acaso». Para problemas de una integración, Home Assistant permite habilitar el registro de depuración de esa integración, reproducir el fallo y desactivarlo para descargar el archivo. El nivel de detalle adicional puede incluir información sensible, por lo que debe revisarse antes de compartirlo.

Reduce el problema sin destruir su contexto

Cuando un bloque tiene veinte condiciones, tres scripts y varias plantillas, crea una copia de prueba o desactiva temporalmente piezas de forma controlada. Conserva:

• Un único disparador reproducible.
• La condición sospechosa.
• La acción mínima y no peligrosa.
• Las entidades necesarias.

Si el problema desaparece, añade una pieza cada vez. Si sigue presente, ya tienes un ejemplo pequeño que resulta más fácil de leer y compartir.

Guarda una copia del fragmento original y evita hacer cinco cambios simultáneos. Si el sistema empieza a funcionar, necesitas saber cuál de ellos lo arregló; si empeora, necesitas poder volver al punto conocido.

Cómo pedir ayuda a Codex de forma útil y segura

Una petición como «arregla este YAML» obliga a adivinar demasiado. Proporciona:

• Versión exacta de Home Assistant.
• Lugar donde está el bloque: automatización de interfaz, archivo manual, script o package.
• Requisito en lenguaje normal.
• Comportamiento esperado y observado.
• Mensaje de error completo o paso de la traza donde se detiene.
• YAML mínimo con secretos y datos personales sustituidos.

Una buena petición sería:

Home Assistant 2026.8.1. Esta automatización manual carga, pero la traza
termina en conditions/0. La puerta está abierta y esperaba que encendiera
la luz. Explica la causa antes de proponer el cambio y dame el parche mínimo.
No cambies los entity_id.

Después de recibir una propuesta, no la pegues a ciegas. Comprueba qué líneas cambian, si introduce conceptos que no entiendes y si conserva los casos negativos. Codex puede detectar patrones y explicar mensajes, pero no conoce el estado real de tu casa si no se lo proporcionas.

Nunca compartas tokens, contraseñas, webhooks, secrets.yaml, copias completas sin revisar ni registros que puedan contener credenciales. Sustituir un secreto por REDACTED no impide diagnosticar la estructura.

Clínica de errores del laboratorio

El laboratorio contiene cinco archivos rotos deliberadamente. No los copies en tu configuración activa. Para cada uno:

1. Anota el síntoma que esperas.
2. Clasifica la capa antes de corregir.
3. Localiza la línea o decisión responsable.
4. Haz el cambio mínimo.
5. Decide qué herramienta demuestra que está corregido.

La solución explica el razonamiento, no solo muestra el YAML final. Algunos fallos se detectan validando; otros requieren Estados, Acciones o una traza. Esa diferencia es el aprendizaje principal.

Tu protocolo a partir de ahora

Cuando algo no funcione, evita recorrer claves al azar hasta que el resultado cambie. Sigue este orden:

1. Define el comportamiento esperado y observado.
2. Confirma que el archivo y la automatización se han cargado.
3. Valida sintaxis y esquema.
4. Recarga de forma selectiva cuando sea posible.
5. Reproduce el evento una vez y anota la hora.
6. Abre la traza; si no existe, investiga el disparador.
7. Consulta estados y prueba la acción mínima.
8. Revisa plantillas con casos normales y estados no disponibles.
9. Lee los registros relacionados.
10. Cambia una sola cosa y repite la prueba.

En el último capítulo aplicaremos este protocolo a un proyecto completo. No bastará con conseguir que «funcione una vez»: construiremos una solución organizada, probaremos sus caminos positivos y negativos y explicaremos por qué toma cada decisión.

Continúa leyendo

Siguiente guía relacionada · 10 min de lectura

Ordena Home Assistant antes de que el YAML se vuelva inmanejable

← Capítulo 9 · Índice del curso Una configuración no se vuelve difícil de mantener porque tenga muchos archivos. Se vuelve difícil cuando no…

Continuar con este artículo↓