Cómo solucionar "YAML parse error" y problemas comunes de indentación en YAML: Una guía completa
YAML (YAML Ain't Markup Language) es muy apreciado por su formato legible para humanos y su sintaxis limpia. Es el estándar para la configuración en herramientas como Kubernetes, Docker Compose, GitHub Actions y muchos generadores de sitios estáticos. Sin embargo, YAML es notablemente estricto con los espacios en blanco y la indentación. Un solo espacio en el lugar equivocado puede provocar un invalid YAML o un YAML parse error difícil de rastrear.
En esta guía, exploraremos los errores de YAML más comunes y cómo solucionarlos rápidamente.
1. Mensajes de error comunes en YAML
Dependiendo de su analizador (como js-yaml o PyYAML de Python), es posible que vea:
YAML parse error: bad indentation of a mapping entry(indentación incorrecta)YAML parse error: found character '\t' that cannot start any token(uso de YAML tab character)invalid YAML: mapping values are not allowed here(valores de mapeo no permitidos)YAML parse error: duplicate key "..."(duplicate key in YAML / clave duplicada)YAML syntax error: end of stream loss
2. Principales causas y soluciones
2.1 Errores de indentación (YAML indentation error)
YAML utiliza la indentación para definir la estructura (como las llaves {} en JSON). Esta debe ser consistente.
El error:
services:
web:
image: nginx
ports: # Indentación incorrecta (3 espacios en lugar de 2 o 4)
- "80:80"
La solución: Asegúrese de que todos los elementos hermanos en un mapa o lista tengan exactamente el mismo número de espacios iniciales. El uso de 2 espacios es el estándar de la industria.
2.2 Caracteres de tabulación (YAML tab character)
YAML prohíbe estrictamente el uso del carácter de tabulación (\t) para la indentación. DEBE usar espacios.
El error:
found character '\t' that cannot start any token
La solución:
Configure su editor de código (VS Code, Sublime, etc.) para "Convertir pestañas en espacios". Si ya ha pegado código con pestañas, use "Buscar y reemplazar" para cambiar \t por .
2.3 Claves duplicadas (duplicate key in YAML)
A diferencia de otros formatos, YAML no permite que la misma clave aparezca dos veces en el mismo nivel de un mapeo.
El error:
image: nginx
ports:
- "80:80"
image: alpine # ¡Clave duplicada!
La solución: Revise su configuración en busca de duplicados accidentales, especialmente en archivos grandes o al fusionar varios archivos.
2.4 Falta de espacio después de los dos puntos
Un error común en YAML es olvidar el espacio después de los dos puntos (:) que separan una clave y su valor.
El error:
url:https://example.com (YAML piensa que esto es una cadena larga)
La solución:
Incluya siempre un espacio: url: https://example.com.
2.5 Cadenas de varias líneas
Si necesita incluir una cadena larga o un bloque de código, debe usar los indicadores escalares de bloque correctos: | (mantiene los saltos de línea) o > (pliega los saltos de línea).
El error:
description: Esta es una
cadena muy larga
sin indicadores. # Esto causará un error de análisis
La solución:
description: |
Esta es una
cadena muy larga
que preserva los saltos de línea.
3. Resolución de problemas avanzada
3.1 Caracteres especiales en los valores
Si su valor contiene caracteres como :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `, podría confundir al analizador.
Solución: Envuelva todo el valor entre comillas dobles ("...") o comillas simples ('...').
3.2 Problemas con booleanos
En YAML 1.1, valores como yes, no, on, off se convierten automáticamente en booleanos (true/false). Esto puede romper las cosas si realmente quería la cadena "no" (como un código de país).
Solución: Siempre ponga entre comillas estas cadenas: country: "NO".
4. Prevención y mejores prácticas
- Use un Linter de YAML: Instale un linter en su editor (por ejemplo,
vscode-yamlde Red Hat) para detectar errores en tiempo real. - Validación de esquemas: Para formatos específicos como Kubernetes o Docker Compose, use sus esquemas oficiales JSON/YAML para la validación.
- Conversión automática: Si se siente más cómodo con JSON, escriba su configuración en JSON y conviértala a YAML con una herramienta.
- Espaciado consistente: Estandarice a 2 espacios para todos los archivos YAML de su proyecto.
5. FAQ: Preguntas frecuentes
P: ¿Por qué mi YAML es válido en un analizador pero no en otro?
R: Hay dos versiones principales de YAML: 1.1 y 1.2. Algunos analizadores (como PyYAML) usan la 1.1 por defecto, mientras que otros usan la 1.2. La versión 1.2 es más compatible con JSON. Si tiene problemas, intente agregar %YAML 1.2 al principio de su archivo.
P: ¿Puedo usar comentarios en YAML?
R: ¡Sí! Esta es una de las grandes ventajas de YAML sobre JSON. Use el símbolo # para los comentarios.
P: ¿Cómo escapo una comilla simple dentro de una cadena con comillas simples?
R: En YAML, las comillas simples se escapan duplicándolas: 'It''s a beautiful day'.
6. Herramienta de comprobación rápida
¿Tiene problemas para encontrar esa pestaña invisible o ese espacio incorrecto? Use nuestro Validador y formateador de YAML (admite conversión de YAML a JSON y validación). Puede:
- Resaltar errores de sintaxis con números de línea.
- Convertir pestañas en espacios automáticamente.
- Embellecer YAML desordenado para una mejor legibilidad.
Errores relacionados
- Cómo solucionar errores de 'Unexpected token in JSON'
- Cómo corregir errores de 'invalid base64 string'
- Entender el desajuste en la codificación de caracteres