Error de indentación en YAML: por qué falla tu despliegue

PublicadoHerramientaValidación y formato de YAML

Contenido
  1. Por qué falla el despliegue en CI: cómo ocurre
  2. Cómo comprobarlo: encontrar la línea que está mal
  3. Los tropiezos más habituales
  4. En resumen
  5. Preguntas frecuentes

Seguro que te ha pasado: tocas un poco el archivo de configuración de GitHub Actions o de GitLab CI, haces commit y recibes un mensaje de que el despliegue ha fallado. Por más que repasas el diff del código, no hay ni una letra cambiada en los comandos, y aun así la causa real suele ser un espacio que casi no se ve. YAML es una sintaxis que marca la jerarquía por el número de espacios de sangría en lugar de usar llaves, así que un solo espacio forma parte de la propia gramática.

Resumen ① YAML es una sintaxis que indica la jerarquía solo con los saltos de línea y el número de espacios de sangría, en lugar de llaves o comas ② Los elementos que están en el mismo nivel deben tener exactamente el mismo número de espacios de sangría; si uno solo se desvía, se interpreta como otro nivel o la estructura se rompe ③ Aunque en pantalla se vea todo alineado, la cantidad real de espacios o si se mezclan tabuladores solo se sabe con certeza al pasarlo por el analizador

Por qué falla el despliegue en CI: cómo ocurre

GitHub Actions, GitLab CI, los manifiestos de Kubernetes, docker-compose… la mayoría de los archivos de configuración de CI/CD se escriben en YAML. YAML no marca el inicio y el final de los elementos secundarios con llaves ni corchetes como JSON, sino que indica la jerarquía únicamente con el número de espacios de sangría de cada línea.

Las líneas que tienen el mismo número de espacios de sangría pertenecen al mismo nivel, y una línea con más sangría se convierte en un elemento secundario de la línea que tiene justo encima. Por esta regla, la cantidad de espacios en sí misma es parte de la gramática, y si el número de espacios no coincide, se interpreta como una estructura completamente distinta.

El problema es que esa diferencia no se ve fácilmente. En la pantalla del editor, unos pocos espacios más o menos se ven igual de alineados, y las líneas que copias y pegas desde otro documento o desde el código de otra persona traen consigo el número de espacios de sangría del original, así que es fácil que queden desalineadas respecto a las líneas de alrededor.

Por ejemplo, si en una lista steps formada por varias etapas a una sola de ellas le falta un espacio, ese elemento se desplaza a un nivel que no le corresponde o el analizador no consigue interpretar la estructura y devuelve un error. En el log de CI muchas veces solo queda un mensaje de fallo muy corto, así que con el log únicamente es difícil saber en qué línea está el problema.

Cómo comprobarlo: encontrar la línea que está mal

Si activas la función de «mostrar caracteres invisibles» del editor, los espacios y los tabuladores aparecen con símbolos distintos, de modo que puedes diferenciar caracteres que en pantalla no se distinguen. La guía de sangría también ayuda a comparar de un vistazo si las líneas del mismo nivel quedan alineadas en una línea vertical.

Si aun así no lo encuentras, siempre puedes contar el archivo línea por línea desde el principio. Tomando como referencia la línea padre, puedes ajustar a mano cuántos espacios tiene de sangría la línea hija hasta dar con el punto desalineado, pero cuanto más largo es el archivo, más tiempo lleva y es fácil equivocarse mientras cuentas.

Compruébalo con nuestra herramienta. Si pegas el YAML tal cual o cargas el archivo, su propio analizador vuelve a interpretar la estructura y te indica directamente el número de la línea cuya sangría está desalineada.

Validación y formato de YAML

Gratis · sin registro · consulta en el navegador la línea exacta del error de YAML

Los tropiezos más habituales

SituaciónCausa
En el editor se ve alineado, pero sigue dando errorHay tabuladores y espacios mezclados: en pantalla parecen iguales, pero el analizador los trata como sangrías distintas
Al pegar un fragmento de YAML copiado de otro documento aparece un errorEl número de espacios de sangría del original no coincide con el de este archivo, así que la jerarquía queda desalineada respecto a las líneas de alrededor
Solo uno de los elementos de una lista (los que empiezan por -) da errorSi los elementos hermanos no tienen exactamente el mismo número de espacios de sangría, ese elemento se separa en otro nivel
El log de CI no muestra el número de la línea del errorEl log solo indica que el análisis falló; para localizar la línea que lo causó tienes que validar el archivo por tu cuenta

Todos los casos de la tabla salen de la misma regla: «el número de espacios de sangría determina la jerarquía». Si pasas el archivo por una herramienta de validación, puedes comprobar directamente con el número de línea esa diferencia que a las personas se nos escapa con facilidad.

En resumen

Los archivos de configuración de CI/CD se escriben en su mayoría en YAML, y YAML indica la jerarquía con el número de espacios de sangría en lugar de con llaves. Los elementos del mismo nivel tienen que tener exactamente el mismo número de espacios, y con que uno solo se desvíe ya se interpretan como otro nivel o el propio análisis falla.

Puedes comprobarlo a ojo con la función de mostrar espacios del editor o contar los espacios a mano, pero cuanto más largo es el archivo, más rápido y fiable resulta pasarlo por una herramienta de validación y mirar directamente el número de línea.

Validación y formato de YAML

Gratis · sin registro · consulta en el navegador la línea exacta del error de YAML

Preguntas frecuentes

En el log de CI no aparece el número de la línea del error, ¿cómo lo encuentro?

El log de la propia herramienta de CI, en la mayoría de los casos, solo indica que «el análisis falló» y no llega a dar el número exacto de la línea. Si pegas el archivo de configuración tal cual en un validador de YAML aparte, el analizador te dirá con el número de línea desde cuál la interpretación de la jerarquía dejó de cuadrar.

¿La sangría va con 2 o con 4 espacios?

La propia especificación de YAML no impone un número de espacios. Eso sí, dentro de un mismo archivo los elementos del mismo nivel deben usar siempre el mismo número de espacios, así que lo importante es unificar en todo el proyecto, ya sea 2 o 4. Los documentos de ejemplo de GitHub Actions y GitLab CI suelen usar 2 espacios.

¿Puedo mezclar tabuladores y espacios?

No. La especificación de YAML no permite el carácter de tabulación en la sangría. El motivo es que cada editor muestra un tabulador con un número de columnas distinto, así que el analizador no puede decidir de forma consistente a cuántos espacios equivale la sangría de un tabulador.

Este artículo está adaptado de nuestro original en coreano. Leer el original en coreano

Artículos relacionados

  1. Subtítulos automáticos de YouTube: por qué fallan y SRT vs VTTPor qué los subtítulos automáticos de YouTube fallan en nombres y términos técnicos, en qué se diferencian de los manuales y cuándo elegir SRT, VTT o TXT.
  2. Numerar líneas de texto: 5 formatos y alineación de dígitosAñade 1., [1] o 01. al inicio de cada línea de un texto o código, excluye las líneas vacías y calcula el relleno con ceros.
  3. Anagramas: cómo comprobar si dos textos lo son (4 pasos)Aprende a comprobar si dos palabras o frases son anagramas: pasos manuales, reglas para mayúsculas y espacios, ejemplos y un algoritmo con tablas hash.
  4. Filtro de palabrotas: enmascarar texto sin falsos positivosAprende a diferenciar coincidencia parcial y total, a priorizar las palabras más largas y a evitar la sobrecensura al ocultar insultos con asteriscos.
  5. Codificación Base32: decodifica tu clave secreta OTPDescubre por qué Base32 evita 0, 1, 8 y 9, cómo funciona el relleno con = y cómo se usa en las claves secretas de Google Authenticator y el 2FA.
  6. Base64: codificación y decodificación sin romper caracteresCómo funciona Base64: el paso de 8 a 6 bits, el 33 % más de tamaño, el relleno con (=) y cómo evitar que se rompan los caracteres UTF-8.

Herramientas relacionadas