Como Detetar e Corrigir Erros de YAML: Sintaxe, Indentação e Validação

O YAML deriva toda a sua estrutura do espaço em branco. Não há parênteses retos, não há chavetas, não há delimitadores de bloco explícitos — apenas níveis de indentação e dois pontos. Isto torna o YAML notavelmente legível quando está correto e notavelmente frustrante quando não está, porque o mesmo carácter que organiza os seus dados pode destruí-los silenciosamente se estiver uma coluna desviado.

O parser reporta onde desistiu, não onde cometeu o erro

A dificuldade central das mensagens de erro de YAML é que os parsers reportam a linha onde deixaram de conseguir interpretar o documento — não a linha onde o erro original foi cometido. Dois pontos em falta na linha 15 podem não aparecer como erro até à linha 22, quando a chave seguinte chega num contexto inesperado. Isto significa que quase sempre precisa de olhar várias linhas acima do erro reportado para encontrar a causa real.

• Os erros de indentação cascata — um bloco pai mal indentado faz cada chave filha reportar erro
• As tabulações parecem idênticas aos espaços mas provocam uma falha de parsing em qualquer parser conforme à especificação
• As chaves duplicadas passam silenciosamente as verificações de sintaxe básicas — um valor é sobreposto sem qualquer aviso
• Os caracteres especiais sem aspas como :, #, * e & alteram o significado do documento inesperadamente
• As âncoras e aliases falham silenciosamente se um alias referenciar uma âncora inexistente no mesmo ficheiro

A versão do YAML importa

A maioria das ferramentas modernas tem como alvo o YAML 1.2, que apertou várias regras de parsing que o YAML 1.1 permitia. Por exemplo, o YAML 1.1 tratava yes, no, on e off como valores booleanos; o YAML 1.2 não. Se a sua configuração usa estas cadeias nuas e o seu validador reporta coerção de tipo inesperada, a discrepância de versão do YAML é a causa. Verifique sempre que versão da especificação o seu parser em tempo de execução implementa.

Os erros de YAML enquadram-se num pequeno número de categorias repetitivas. Reconhecer a categoria a partir da mensagem de erro — ou da aparência visual do ficheiro — corta o tempo de diagnóstico de minutos para segundos.

Erros de indentação

O YAML exige indentação consistente. A especificação não impõe um número específico de espaços, mas cada nível deve estar indentado mais que o seu pai pela mesma quantidade dentro desse bloco. Misturar indentação de dois e quatro espaços no mesmo ficheiro, ou indentar um item de sequência um espaço menos que o seu irmão, produzirá um erro de «indentação inesperada» ou «não foi possível encontrar a entrada de bloco esperada». A prática mais segura é dois espaços por nível em todo o ficheiro.

Tabulações em vez de espaços

A especificação YAML proíbe explicitamente tabulações como indentação. A maioria dos parsers lança um erro de «carácter encontrado que não pode iniciar nenhum token» ou «tabulação presente no início de uma linha» quando encontra uma. O problema é invisível na maioria dos editores a menos que ative uma opção de «mostrar espaços» ou «renderizar espaços». Configure o seu editor para expandir sempre tabulações em espaços nos ficheiros .yaml e .yml para eliminar esta categoria por completo.

Cadeias sem aspas com caracteres especiais

O YAML reserva vários caracteres para fins estruturais: dois pontos, cardinal, asterisco, ampersand, ponto de exclamação, pipe, maior que, parênteses retos e chavetas. Quando qualquer um destes caracteres aparece num valor de cadeia sem aspas, o parser pode interpretá-los mal como tokens de sintaxe. A manifestação mais comum é um valor de URL como https://example.com:8080 que provoca um erro de «valores de mapeamento não permitidos aqui» porque o :8080 é parseado como uma nova chave de mapeamento. Coloque aspas em qualquer valor de cadeia que contenha estes caracteres.

As mensagens de erro de YAML são notoriamente lacónicas. Entender como descodificar as duas ou três informações que realmente fornecem poupa um tempo considerável de depuração. Cada mensagem de parser contém uma referência de linha e coluna, uma descrição do que era esperado e, às vezes, uma descrição do que foi encontrado em vez disso.

Um erro na linha 30, coluna 1, normalmente significa que o problema começou na linha 20. Leia para cima.

As três partes de um erro de parser

• Linha e coluna: aponta para onde o parsing falhou, não necessariamente onde está o erro — olhe 5-10 linhas acima
• Token esperado: o que o parser procurava — «esperava-se um valor de mapeamento» significa que esperava dois pontos após uma chave
• Token encontrado: o que o parser realmente encontrou — «encontrada uma entrada de sequência de bloco» significa que chocou com um item de lista - onde esperava uma chave

Descodificar padrões de mensagens comuns

"could not find expected ':'" significa que o parser leu uma chave de mapeamento mas chegou ao fim da linha ou a um token que não eram dois pontos antes de encontrar o separador. A chave pode conter um carácter reservado que terminou o token de chave cedo demais, ou os dois pontos foram omitidos acidentalmente. "mapping values are not allowed here" significa que um : apareceu num contexto em que o parser não estava num bloco de mapeamento — tipicamente causado por um URL ou cadeia de versão sem aspas. "found duplicate key" é levantada por parsers rigorosos (yaml.v3 de Go, ruamel.yaml) quando o mesmo nome de chave aparece mais de uma vez num bloco — uma alteração de configuração em que a chave antiga não foi removida.

O caminho mais rápido de um ficheiro YAML partido para um funcional é um fluxo de trabalho estruturado e consciente das categorias, em vez de uma inspeção visual linha a linha. Estes cinco passos cobrem cada cenário comum.

Diferentes tipos de ficheiros YAML atraem diferentes padrões de erro. Saber que erros são mais comuns em cada tipo de ficheiro permite-lhe verificar primeiro o que importa em vez de varrer o documento inteiro.

Workflows do GitHub Actions

Os workflows do GitHub Actions falham na fase de parsing antes de qualquer job executar, tornando os erros de YAML a primeira coisa a corrigir. Os erros mais comuns são on: tratado como booleano (true) porque on é um booleano YAML 1.1 — coloque-lhe aspas como "on" ou use o nome completo do trigger. Os blocos run: de passos com scripts de shell multilinha que usam o indicador de bloco escalar errado (dobrado > em vez de literal |) também causam erros silenciosos onde as novas linhas são colapsadas. Use | para scripts de shell multilinha. O Validador de Workflows do GitHub Actions verifica tanto a sintaxe YAML como as regras estruturais específicas de workflow numa só passagem.

Manifestos de Kubernetes

Os erros de YAML de Kubernetes tipicamente envolvem erros profundos de indentação aninhada — um bloco containers indentado sob spec por quatro espaços quando os blocos circundantes usam dois, ou um bloco resources.limits colocado ao nível de aninhamento errado. O servidor API de Kubernetes reporta-os como erros de validação de campos, não como erros de sintaxe YAML, porque o kubectl apply primeiro parseia o YAML com sucesso e depois valida o esquema do objeto. Use o Validador de Kubernetes para capturar problemas tanto de YAML como de esquema antes de aplicar. O Realçador de Diffs para Configs JSON/YAML é útil para comparar manifestos entre ambientes.

Ficheiros de Docker Compose

Os erros de docker-compose.yml do Docker Compose são mais comumente erros de indentação nas definições de serviços, mapeamentos de portas sem aspas como 3000:3000 (os dois pontos provocam um erro do parser salvo se asparelhados ou escritos como item de sequência), e valores de variáveis de ambiente que contêm sinais de igual ou cardinais sem aspas. Coloque sempre aspas nos valores das variáveis de ambiente. O Validador de Docker Compose valida tanto a estrutura YAML como o esquema específico do Compose.

Ficheiros values.yaml do Helm

Os ficheiros values.yaml do Helm frequentemente usam âncoras YAML para configuração DRY — e erros relacionados com âncoras são comuns após reestruturação. O Validador de Values do Helm valida a sintaxe específica do Helm, enquanto a Ferramenta de Diff de Deriva YAML dos Values do Helm ajuda-o a comparar valores entre releases para capturar a deriva introduzida por uma edição recente.

Playbooks do Ansible

Os playbooks do Ansible combinam YAML padrão com expressões de template Jinja2 usando chavetas duplas em volta de nomes de variáveis. As chavetas duplas não são sintaxe YAML, mas aparecem dentro de valores de cadeia YAML. Se uma expressão Jinja aparecer como o valor inteiro de uma chave sem aspas, o parser YAML do Ansible trata a chaveta de abertura como o início de um mapeamento de fluxo. Coloque sempre aspas em qualquer valor YAML que comece por chavetas duplas. O Validador de Ansible trata tanto a camada YAML como a Jinja2 da validação de playbooks.

Para além da sintaxe básica, várias funcionalidades de YAML têm as suas próprias categorias de erro que requerem abordagens de diagnóstico específicas. São menos comuns mas tendem a ser mais difíceis de diagnosticar sem as ferramentas certas.

Chaves duplicadas — perda silenciosa de dados

As chaves duplicadas são a categoria de erro de YAML mais perigosa porque não provocam uma falha de parsing na maioria dos parsers. Quando refatoriza um ficheiro de configuração e adiciona um novo valor a uma chave sem remover o antigo, ambas as chaves coexistem no texto bruto. Dependendo do parser, ganha o primeiro ou o último valor — PyYAML e js-yaml usam silenciosamente a última ocorrência, enquanto o yaml.v3 de Go reporta um erro. O resultado é um ficheiro de configuração que parece correto ao lê-lo mas comporta-se em tempo de execução de forma diferente da esperada.

Erros de âncoras e aliases

As âncoras YAML (&name) permitem definir um valor uma vez e referenciá-lo noutro lugar com um alias (*name). Os erros ocorrem quando um alias referencia uma âncora declarada mais tarde no ficheiro (referências para a frente não são permitidas em YAML), quando duas âncoras partilham o mesmo nome (a segunda sobrepõe silenciosamente a primeira), ou quando uma merge key (<<: *alias) é usada num nó que não é um mapeamento. Estes erros são invisíveis para validadores básicos — só um validador que rastreie especificamente as declarações de âncoras e as referências de aliases os apanhará.

Desajustes de substituição de variáveis de ambiente

Docker Compose, GitHub Actions e Ansible suportam todos a substituição de variáveis de ambiente dentro dos valores YAML. Quando a variável de ambiente não está definida no momento do parsing, a substituição falha, usa uma cadeia vazia ou recorre a um valor predefinido — dependendo da sintaxe usada. Um documento YAML que valida corretamente em CI pode falhar em produção porque falta uma variável de ambiente obrigatória. A Ferramenta de Pré-visualização de Substituição de Env YAML permite-lhe pré-visualizar o documento YAML expandido com um conjunto específico de valores de variáveis antes da implantação.

• $VAR sem valor predefinido: falha silenciosamente se VAR não estiver definida — substitui uma cadeia vazia
• Sintaxe ${VAR:-default}: recorre a "default" se VAR não estiver definida — teste ambos os caminhos
• Sintaxe ${VAR:?error message}: lança um erro explícito se VAR não estiver definida — preferido para variáveis obrigatórias
• Substituições sem aspas que começam por chaveta: o parser trata as substituições de variáveis como mapeamentos de fluxo — coloque sempre aspas

Corrigir erros individuais de YAML é rápido uma vez que conheça a categoria. Prevenir que cheguem à produção requer um pequeno conjunto de hábitos consistentes e verificações automatizadas.

Configuração do editor

Configure o seu editor para usar indentação de dois espaços em ficheiros YAML, inserir espaços em vez de tabulações e ativar os espaços visíveis. No VS Code, instale a extensão YAML da Red Hat que fornece verificação de sintaxe em tempo real, validação de esquema (para Kubernetes, GitHub Actions e outros formatos com JSON Schemas publicados) e autocompletamento. Adicione um ficheiro .editorconfig ao seu projeto para impor estas configurações a cada membro da equipa independentemente da configuração local do seu editor.

• Configurações de .editorconfig para YAML: indent_style = space, indent_size = 2, trim_trailing_whitespace = true
• VS Code: instale a extensão YAML (Red Hat) — valida esquema e sintaxe em tempo real
• IDEs JetBrains: ative o suporte YAML e defina o nível de inspeção como Warning para erros estruturais
• Vim/Neovim: use yaml-language-server via nvim-lspconfig para diagnósticos em linha
• Prettier: formata YAML de forma consistente — previne a deriva de espaços e indentação entre membros da equipa

Validação automatizada em CI/CD

Adicione um passo de linting de YAML ao seu pipeline de CI que corra em cada pull request que toque em qualquer ficheiro .yaml ou .yml. O yamllint é a ferramenta CLI padrão — valida sintaxe, verifica chaves duplicadas, impõe limites de comprimento de linha e apanha problemas de coerção de cadeias truthy. Configure-o com um ficheiro .yamllint.yaml na raiz do seu projeto e adicione-o como hook de pre-commit ou passo de CI que corra antes de quaisquer jobs de implantação.

Disciplina de revisão de código

Os diffs de YAML na revisão de código são enganosamente fáceis de aprovar sem apanhar erros. Indentação de dois espaços versus quatro parece uma preferência de formatação mas altera a estrutura do documento. Uma chave movida para um nível de indentação diferente altera o seu bloco pai. Use o Realçador de Diffs para Configs JSON/YAML para rever as alterações de YAML semanticamente — mostra que chaves foram adicionadas, removidas ou alteradas por valor em vez de por diff de linhas brutas, tornando as alterações estruturais imediatamente visíveis.