Guia

Erros comuns de YAML

Seis erros causam quase todos os parsings falhados. Eis o que cada um significa — e a correção exata.

Por yamltojsonfree · Publicado em 25 de agosto de 2026 · Atualizado em 1 de setembro de 2026

Porque é que os erros de YAML são tão difíceis de ler

O YAML constrói a estrutura a partir da indentação, por isso quando algo corre mal o parser muitas vezes não consegue dizer o que correu mal — apenas que a estrutura deixou de fazer sentido. É por isso que um parêntese por fechar na linha 12 é rotineiramente reportado como «indentação incorreta» na linha 50: o parser continuou a consumir linhas, à procura de um delimitador de fecho que nunca chegou, e só desistiu muito mais tarde.

Os erros abaixo estão listados pela sua causa real, não pela mensagem que um parser imprime. Se preferir que sejam diagnosticados automaticamente, cole o seu documento no validador de YAML ou no conversor de YAML para JSON — cada um destes erros é detetado como o que é, com a linha, uma explicação clara e uma correção sugerida.

Os seis erros, em detalhe

Os seis erros de sintaxe YAML mais comuns são: (1) uma tabulação usada para indentar, (2) um valor sem aspas que contém dois pontos, (3) um parêntese, chaveta ou aspa por fechar, (4) uma chave duplicada, (5) um alias para um anchor que não existe e (6) chaves irmãs indentadas de forma diferente.

1. Um carácter de tabulação é usado para indentar

Porquê: O YAML proíbe por completo tabulações na indentação, porque a sua largura é ambígua entre editores.

Correção: Substitua cada tabulação por espaços — dois por nível é a convenção. A maioria dos editores faz isto com «converter indentação em espaços».

2. Um valor sem aspas contém dois pontos

Porquê: title: foo: bar é ambíguo — o parser não consegue saber que dois pontos separam a chave do valor.

Correção: Ponha o valor entre aspas: title: 'foo: bar'.

3. Um parêntese, chaveta ou aspa nunca é fechado

Porquê: Coleções de fluxo como [80, 443] e strings entre aspas têm de ser fechadas na mesma linha lógica. A maioria dos parsers reporta isto como erro de indentação muitas linhas depois.

Correção: Acrescente o delimitador de fecho, ou reescreva o valor em estilo de bloco com uma entrada por linha.

4. A mesma chave aparece duas vezes

Porquê: Os mapas YAML exigem chaves únicas, e os objetos JSON também. Ficar em silêncio com o último valor esconderia um bug real.

Correção: Renomeie ou remova o duplicado — ou indente-o um nível para dentro se era para ser uma sub-chave.

5. Um alias aponta para um anchor que não existe

Porquê: *nome refere-se a um anchor definido com &nome. Os anchors têm de aparecer no documento antes dos aliases que os usam.

Correção: Defina primeiro o anchor e verifique a ortografia — os nomes dos anchors distinguem maiúsculas de minúsculas.

6. Chaves irmãs estão indentadas de forma diferente

Porquê: Todas as chaves do mesmo bloco têm de estar na mesma indentação. Dois espaços numa linha e três na seguinte terminam o bloco antes do tempo.

Correção: Torne idêntica a indentação de todas as chaves irmãs.

Duas correções, antes e depois

Os dois erros em que mais se tropeça, mostrados como YAML com erro ao lado da forma corrigida.

Dois pontos sem aspas num valor

Os segundos dois pontos tornam a linha ambígua; pôr todo o valor entre aspas resolve.

Com erro

title: Deploy: production
owner: platform team

Corrigido

title: "Deploy: production"
owner: platform team

Indentação irregular entre irmãs

«ports» está a três espaços enquanto as irmãs estão a dois, por isso o bloco termina antes do tempo.

Com erro

server:
  host: localhost
   ports:
    - 8080

Corrigido

server:
  host: localhost
  ports:
    - 8080

Quando o YAML é válido mas continua errado

Um documento pode passar perfeitamente no parsing e ainda assim significar algo que não pretendia. O caso clássico é country: NO, YAML válido em todas as versões — mas lido como a string "NO" em YAML 1.2 e como o booleano false em YAML 1.1. Toda essa classe de mudanças de tipo silenciosas é tratada no guia YAML 1.1 vs 1.2.

Referências

Especificação YAML 1.2.2 — as regras de indentação, coleções de fluxo, anchors e chaves únicas
YAML 1.2.2 §6.1 Espaços de indentação — porque é que tabulações não são permitidas
Documentação do PyYAML — as mensagens de erro que a maioria dos utilizadores de Python vê
js-yaml — o parser por trás das ferramentas deste site

Corrija o seu YAML agora

Todos os erros desta página são detetados com a linha exata e uma correção sugerida pelas ferramentas gratuitas deste site. Nada é enviado — tudo corre no seu navegador.

YAML 1.1 vs 1.2

Por que country: NO pode virar false e como escrever YAML seguro.

Ler guia

Converter YAML para JSON em código

Exemplos em Python, Node.js, Go e yq para conversões repetiveis.