T
yaml debugging configuration web-development devops

Resolvendo o 'YAML parse error' e problemas comuns de indentação YAML

Um guia abrangente para corrigir erros YAML, como 'invalid YAML', 'YAML indentation error' e problemas de 'YAML tab character'. Aprenda as regras estritas da sintaxe YAML.

2026-04-11

Resolvendo o "YAML parse error" e problemas comuns de indentação YAML: Um Guia Completo

O YAML (YAML Ain't Markup Language) é amado por seu formato legível por humanos e sintaxe limpa. É o padrão para configuração em ferramentas como Kubernetes, Docker Compose, GitHub Actions e muitos geradores de sites estáticos. No entanto, o YAML é notoriamente rigoroso com espaços em branco e indentação. Um único espaço no lugar errado pode levar a um invalid YAML ou YAML parse error difícil de rastrear.

Neste guia, exploraremos os erros de YAML mais comuns e como corrigi-los rapidamente.

1. Mensagens de erro YAML comuns

Dependendo do seu analisador (como js-yaml ou PyYAML do Python), você poderá ver:

  • YAML parse error: bad indentation of a mapping entry (indentação incorreta)
  • 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 mapeamento não permitidos aqui)
  • YAML parse error: duplicate key "..." (duplicate key in YAML / chave duplicada)
  • YAML syntax error: end of stream loss

2. Principais causas e soluções

2.1 Erros de indentação (YAML indentation error)

O YAML usa indentação para definir a estrutura (como as chaves {} no JSON). Ela deve ser consistente.

O erro:

services:
  web:
    image: nginx
   ports:  # Indentação incorreta (3 espaços em vez de 2 ou 4)
      - "80:80"

A solução: Certifique-se de que todos os elementos irmãos em um mapa ou lista tenham exatamente o mesmo número de espaços iniciais. O uso de 2 espaços é o padrão da indústria.

2.2 Caracteres de tabulação (YAML tab character)

O YAML proíbe estritamente o uso do caractere de tabulação (\t) para indentação. Você DEVE usar espaços.

O erro: found character '\t' that cannot start any token

A solução: Configure seu editor de código (VS Code, Sublime, etc.) para "Converter tabulações em espaços". Se você já colou código com tabulações, use "Localizar e substituir" para trocar \t por .

2.3 Chaves duplicadas (duplicate key in YAML)

Ao contrário de alguns outros formatos, o YAML não permite que a mesma chave apareça duas vezes no mesmo nível de um mapeamento.

O erro:

image: nginx
ports:
  - "80:80"
image: alpine  # Chave duplicada!

A solução: Verifique sua configuração para duplicatas acidentais, especialmente em arquivos grandes ou ao mesclar vários arquivos.

2.4 Falta de espaço após os dois pontos

Um erro comum no YAML é esquecer o espaço após os dois pontos (:) que separam uma chave e seu valor.

O erro: url:https://example.com (YAML pensa que esta é uma string longa)

A solução: Sempre inclua um espaço: url: https://example.com.

2.5 Strings de várias linhas

Se precisar incluir uma string longa ou um bloco de código, você deve usar os indicadores escalares de bloco corretos: | (mantém as quebras de linha) ou > (dobra as quebras de linha).

O erro:

description: Esta é uma
string muito longa
sem indicadores. # Isso causará um erro de análise

A solução:

description: |
  Esta é uma
  string muito longa
  que preserva as quebras de linha.

3. Solução de problemas avançada

3.1 Caracteres especiais nos valores

Se o seu valor contiver caracteres como :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `, isso pode confundir o analisador. Solução: Envolva todo o valor em aspas duplas ("...") ou aspas simples ('...').

3.2 Armadilhas de booleanos

No YAML 1.1, valores como yes, no, on, off são convertidos automaticamente em booleanos (true/false). Isso pode quebrar as coisas se você realmente quisesse a string "no" (como um código de país). Solução: Sempre use aspas nessas strings: country: "NO".

4. Prevenção e melhores práticas

  1. Use um Linter de YAML: Instale um linter em seu editor (ex: vscode-yaml da Red Hat) para capturar erros em tempo real.
  2. Validação de esquema: Para formatos específicos como Kubernetes ou Docker Compose, use seus esquemas oficiais JSON/YAML para validação.
  3. Conversão automatizada: Se você se sente mais confortável com JSON, escreva sua configuração em JSON e converta-a para YAML usando uma ferramenta.
  4. Espaçamento consistente: Padronize em 2 espaços para todos os arquivos YAML em seu projeto.

5. FAQ: Perguntas frequentes

P: Por que meu YAML é válido em um analisador, mas não em outro?

R: Existem duas versões principais do YAML: 1.1 e 1.2. Alguns analisadores (como PyYAML) usam a versão 1.1 por padrão, enquanto outros usam a 1.2. A versão 1.2 é mais compatível com JSON. Se encontrar problemas, tente adicionar %YAML 1.2 no topo do seu arquivo.

P: Posso usar comentários no YAML?

R: Sim! Esta é uma das grandes vantagens do YAML sobre o JSON. Use o símbolo # para comentários.

P: Como escapo uma aspa simples dentro de uma string entre aspas simples?

R: No YAML, você escapa uma aspa simples duplicando-a: 'It''s a beautiful day'.

6. Ferramenta de verificação rápida

Está tendo problemas para encontrar aquele tab invisível ou espaço incorreto? Use nosso Validador e Formatador YAML (suporta conversão de YAML para JSON e validação). Ele pode:

  • Destacar erros de sintaxe com números de linha.
  • Converter tabs em espaços automaticamente.
  • Embelezar YAML bagunçado para melhor legibilidade.

Erros relacionados

  • Resolvendo erros 'Unexpected token in JSON'
  • Como corrigir erros de 'invalid base64 string'
  • Entendendo incompatibilidades de codificação de caracteres
Voltar ao blog