Guía

Errores comunes de YAML

Seis fallos causan casi todos los análisis fallidos. Esto es lo que significa cada uno — y la solución exacta.

Por yamltojsonfree · Publicado el 25 de agosto de 2026 · Actualizado el 1 de septiembre de 2026

Por qué los errores de YAML son tan difíciles de leer

YAML construye la estructura a partir de la indentación, así que cuando algo falla el analizador a menudo no puede saber qué falló — solo que la estructura dejó de tener sentido. Por eso un corchete sin cerrar en la línea 12 se reporta habitualmente como «indentación incorrecta» en la línea 50: el analizador siguió consumiendo líneas, buscando un delimitador de cierre que nunca llegó, y solo se rindió mucho después.

Los errores siguientes están ordenados por su causa real, no por el mensaje que imprime un analizador. Si prefieres que se diagnostiquen automáticamente, pega tu documento en el validador de YAML o en el conversor de YAML a JSON — cada uno de estos errores se detecta como lo que es, con la línea, una explicación clara y una solución sugerida.

Los seis errores, en detalle

Los seis errores de sintaxis YAML más comunes son: (1) un tabulador usado para indentar, (2) un valor sin comillas que contiene dos puntos, (3) un corchete, llave o comilla sin cerrar, (4) una clave duplicada, (5) un alias a un ancla que no existe y (6) claves hermanas indentadas de forma distinta.

1. Se usa un tabulador para indentar

Por qué: YAML prohíbe por completo los tabuladores para indentar, porque su anchura es ambigua entre editores.

Solución: Sustituye cada tabulador por espacios — dos por nivel es lo habitual. La mayoría de editores pueden hacerlo con «convertir indentación a espacios».

2. Un valor sin comillas contiene dos puntos

Por qué: title: foo: bar es ambiguo — el analizador no puede saber qué dos puntos separan la clave del valor.

Solución: Pon el valor entre comillas: title: 'foo: bar'.

3. Un corchete, llave o comilla nunca se cierra

Por qué: Las colecciones de flujo como [80, 443] y las cadenas entre comillas deben cerrarse en la misma línea lógica. La mayoría de analizadores lo reportan como un error de indentación muchas líneas después.

Solución: Añade el delimitador de cierre, o reescribe el valor en estilo de bloque con una entrada por línea.

4. La misma clave aparece dos veces

Por qué: Los mapas YAML requieren claves únicas, y los objetos JSON también. Quedarse en silencio con el último valor ocultaría un error real.

Solución: Renombra o elimina el duplicado — o indéntalo un nivel más si pretendía ser una subclave.

5. Un alias apunta a un ancla que no existe

Por qué: *nombre hace referencia a un ancla definida con &nombre. Las anclas deben aparecer en el documento antes que los alias que las usan.

Solución: Define primero el ancla y comprueba la ortografía — los nombres de las anclas distinguen mayúsculas y minúsculas.

6. Las claves hermanas tienen distinta indentación

Por qué: Todas las claves del mismo bloque deben estar a la misma indentación. Dos espacios en una línea y tres en la siguiente terminan el bloque antes de tiempo.

Solución: Haz que la indentación de todas las claves hermanas sea idéntica.

Dos correcciones, antes y después

Los dos errores con los que más se tropieza, mostrados como YAML roto junto a su forma corregida.

Dos puntos sin comillas en un valor

Los segundos dos puntos hacen la línea ambigua; poner todo el valor entre comillas lo resuelve.

Roto

title: Deploy: production
owner: platform team

Corregido

title: "Deploy: production"
owner: platform team

Indentación desigual entre hermanos

«ports» está a tres espacios mientras sus hermanos están a dos, así que el bloque termina antes de tiempo.

Roto

server:
  host: localhost
   ports:
    - 8080

Corregido

server:
  host: localhost
  ports:
    - 8080

Cuando el YAML es válido pero sigue estando mal

Un documento puede analizarse perfectamente y aun así significar algo que no pretendías. El caso clásico es country: NO, YAML válido en todas las versiones — pero que se lee como la cadena "NO" en YAML 1.2 y como el booleano false en YAML 1.1. Toda esa clase de cambios de tipo silenciosos se trata en la guía YAML 1.1 frente a 1.2.

Referencias

Especificación YAML 1.2.2 — las reglas de indentación, colecciones de flujo, anclas y claves únicas
YAML 1.2.2 §6.1 Espacios de indentación — por qué no se permiten tabuladores
Documentación de PyYAML — los mensajes de error que ven la mayoría de usuarios de Python
js-yaml — el analizador detrás de las herramientas de este sitio

Corrige tu YAML ahora

Todos los errores de esta página los detectan las herramientas gratuitas de este sitio con la línea exacta y una solución sugerida. Nada se sube — todo se ejecuta en tu navegador.

YAML 1.1 frente a 1.2

Por qué country: NO puede convertirse en false, el problema Norway y cómo escribir YAML seguro.

Leer la guía

Convertir YAML a JSON en código

Ejemplos en Python, Node.js, JavaScript, C#, Go y yq para conversiones repetibles.