How to Fix Invalid JSON: Common Errors & Solutions

Por que a Análise de JSON Falha

JSON parece simples — e é — mas sua rigidez é exatamente o que confunde as pessoas. Ao contrário dos literais de objeto do JavaScript, o JSON não tolera atalhos de sintaxe. Sem vírgulas finais. Sem aspas simples. Sem comentários. Cada desvio produz um erro de análise, e as mensagens de erro geralmente são pouco úteis: Token inesperado ou JSON.parse: esperado ',' ou '}' na linha 1.

Este guia cobre os 10 erros mais comuns de JSON que os desenvolvedores encontram na prática. Cada um inclui o JSON quebrado, por que o analisador o rejeita e a versão corrigida. Adicione esta página aos seus favoritos — você vai voltar a ela.

Experimente você mesmo: Cole JSON quebrado em nossa ferramenta de Reparo de JSON para corrigir automaticamente a maioria desses erros instantaneamente.

Erro 1: Vírgula Final

Este é o erro de JSON mais comum. O JavaScript permite vírgulas finais em objetos e arrays, então os desenvolvedores naturalmente escrevem JSON da mesma forma. Mas o JSON não permite isso.

Quebrado:

{
  "name": "Alice",
  "age": 30,
}

Corrigido:

{
  "name": "Alice",
  "age": 30
}

A vírgula final após 30 faz com que o analisador espere outro par chave-valor. Quando encontra uma chave de fechamento em vez disso, ele falha. Remova a vírgula após o último item em cada objeto e array.

Erro 2: Aspas Simples em vez de Aspas Duplas

O JSON requer aspas duplas para chaves e valores de string. Aspas simples são uma característica do JavaScript que o analisador de JSON rejeita imediatamente.

Quebrado:

{
  'name': 'Alice',
  'city': 'Portland'
}

Corrigido:

{
  "name": "Alice",
  "city": "Portland"
}

Isso acontece com mais frequência ao copiar literais de objeto do código JavaScript ou de dicionários Python (que também usam aspas simples). Uma busca e substituição de ' por " corrige isso, mas tenha cuidado com strings que contêm apóstrofos — essas precisam ser escapadas.

Erro 3: Chaves Não Entre Aspas

O JavaScript permite que você escreva { name: "Alice" } sem colocar a chave entre aspas. O JSON não. Cada chave deve ser uma string entre aspas duplas.

Quebrado:

{
  name: "Alice",
  age: 30
}

Corrigido:

{
  "name": "Alice",
  "age": 30
}

Isso geralmente aparece quando alguém escreve JSON manualmente ou copia um objeto JavaScript sem convertê-lo. Alguns editores e ferramentas de depuração de API exibirão chaves não entre aspas, mascarando o problema até que você tente analisar o arquivo em outro lugar.

Erro 4: Comentários em JSON

O JSON não suporta comentários — nem // de linha única, nem /* */ de bloco. Esta é uma das limitações mais frustrantes do formato, especialmente para arquivos de configuração.

Quebrado:

{
  // Configurações do banco de dados
  "host": "localhost",
  "port": 5432 /* porta padrão do PostgreSQL */
}

Corrigido:

{
  "host": "localhost",
  "port": 5432
}

Se você precisar de comentários em arquivos de configuração, considere usar JSONC (JSON com Comentários), que o VS Code e o TypeScript suportam nativamente, ou mude para YAML ou TOML. Para JSON padrão, remova todos os comentários antes de analisar.

Erro 5: Vírgula Faltando Entre Itens

Ao adicionar um novo campo a um objeto JSON, é fácil esquecer a vírgula que o separa do campo anterior. O analisador vê dois valores consecutivos sem separador e falha.

Quebrado:

{
  "name": "Alice"
  "age": 30
}

Corrigido:

{
  "name": "Alice",
  "age": 30
}

A mensagem de erro geralmente aponta para a linha após a vírgula faltante, o que pode ser enganoso. Se você ver String inesperada ou Vírgula esperada, olhe para a linha acima da posição relatada.

Erro 6: Colchete ou Chave de Fechamento Faltando

Colchetes não combinados são difíceis de detectar em grandes arquivos JSON. Um ] ou } faltando faz com que o analisador leia além do final pretendido de uma estrutura, produzindo erros confusos longe do problema real.

Quebrado:

{
  "users": [
    { "name": "Alice" },
    { "name": "Bob" }
}

Corrigido:

{
  "users": [
    { "name": "Alice" },
    { "name": "Bob" }
  ]
}

A correção: use um editor com correspondência de colchetes (o VS Code destaca pares correspondentes) ou um Validador de JSON que relata a localização exata da incompatibilidade.

Erro 7: undefined, NaN ou Infinity

Esses são valores válidos do JavaScript, mas não têm representação em JSON. JSON.stringify converte silenciosamente undefined em null (ou omite a chave completamente), mas se você escrever esses valores manualmente, o analisador os rejeita.

Quebrado:

{
  "score": NaN,
  "callback": undefined,
  "limit": Infinity
}

Corrigido:

{
  "score": null,
  "callback": null,
  "limit": null
}

Substitua undefined e NaN por null, ou omita a chave completamente se a ausência de um valor for semanticamente apropriada. Para Infinity, considere usar um número sentinela ou uma representação de string como "Infinity" e tratá-la no seu código de aplicação.

Erro 8: Vírgula Extra Após o Último Item do Array

Este é a versão de array do Erro 1. Ele aparece constantemente em arquivos JSON editados manualmente, especialmente após a exclusão ou reordenação de itens.

Quebrado:

{
  "colors": [
    "red",
    "green",
    "blue",
  ]
}

Corrigido:

{
  "colors": [
    "red",
    "green",
    "blue"
  ]
}

O padrão é o mesmo: a vírgula após "blue" diz ao analisador para esperar outro elemento. Ele encontra ] em vez disso e relata um erro. Ao remover itens de um array JSON, sempre verifique se o novo último item tem uma vírgula final.

Erro 9: Aspas Inteligentes (Aspas Curvas)

Este é traiçoeiro. Quando você copia JSON de um documento do Word, mensagem do Slack ou um post de blog, seu sistema pode silenciosamente substituir aspas retas (") por aspas tipográficas "inteligentes" (\u201C e \u201D). Elas parecem quase idênticas, mas são caracteres completamente diferentes.

Quebrado:

{
  \u201Cname\u201D: \u201CAlice\u201D,
  \u201Ccity\u201D: \u201CPortland\u201D
}

Corrigido:

{
  "name": "Alice",
  "city": "Portland"
}

A mensagem de erro geralmente é Token inesperado na posição 1 ou 2, o que é confuso até você perceber que os caracteres de aspas estão errados. A correção: substitua todas as aspas curvas por aspas duplas retas. Em uma emergência, reescreva as aspas manualmente em um editor de texto simples.

Para evitar isso, sempre use um editor de código (não um editor de texto rico) para escrever JSON. Desative "aspas inteligentes" nas configurações do teclado do seu sistema operacional se você frequentemente colar entre aplicativos.

Erro 10: Caracteres BOM (Byte Order Mark)

Um BOM é um caractere invisível (U+FEFF) que alguns editores de texto do Windows inserem no início de um arquivo para indicar a codificação. Os analisadores de JSON o veem como um caractere inesperado antes da chave de abertura e falham imediatamente.

Sintomas:

SyntaxError: Token inesperado \uFEFF em JSON na posição 0

Você não consegue ver o BOM na maioria dos editores — ele é realmente invisível. Para detectá-lo, abra o arquivo em um editor hexadecimal e procure os bytes EF BB BF (BOM UTF-8) no início.

Como corrigir:

• No VS Code, clique no indicador de codificação na barra de status e escolha "Salvar com Codificação" → "UTF-8" (sem BOM).
• Na linha de comando: sed -i '1s/^\xEF\xBB\xBF//' file.json
• No Node.js, remova-o antes de analisar: const clean = text.replace(/^\\uFEFF/, "");

Referência Rápida: Todos os 10 Erros

#	Erro	Causa	Correção
1	Vírgula final	Vírgula após o último campo/elemento	Remova a vírgula final
2	Aspas simples	Usou ' em vez de "	Substitua por aspas duplas
3	Chaves não entre aspas	Chaves sem aspas duplas	Coloque todas as chaves entre aspas duplas
4	Comentários	// ou /* */ em JSON	Remova todos os comentários
5	Vírgula faltando	Sem vírgula entre itens	Adicione vírgula entre os itens
6	Colchete/chave de fechamento faltando	[ ou { não fechado	Adicione o caractere de fechamento faltante
7	undefined / NaN / Infinity	Valores apenas do JS em JSON	Substitua por null ou uma string
8	Vírgula extra no array	Vírgula final no array	Remova a vírgula final
9	Aspas inteligentes	Aspas curvas do Word/Slack	Substitua por aspas duplas retas
10	Caractere BOM	U+FEFF invisível no início do arquivo	Re-salve como UTF-8 sem BOM

Prevenindo Erros de JSON

Corrigir erros é bom. Não criá-los em primeiro lugar é melhor. Aqui estão os hábitos que mantêm o JSON limpo:

• Nunca escreva JSON manualmente. Gere-o a partir do código usando JSON.stringify ou o equivalente da sua linguagem. Serializadores produzem JSON válido por definição.
• Use um editor ciente de JSON. VS Code, IDEs JetBrains e Sublime Text destacam erros de sintaxe JSON em tempo real. Se você ver um sublinhado vermelho, corrija antes de salvar.
• Valide no CI. Adicione uma etapa de validação ao seu pipeline de construção que analisa todos os arquivos JSON e falha em caso de erros. Uma única linha de script shell faz isso: find . -name "*.json" -exec python -m json.tool {} \\;
• Use JSONC para configuração. Se você precisar de comentários, use JSONC (extensão .jsonc) onde suportado. TypeScript, VS Code e muitas outras ferramentas lidam com isso nativamente.

Quando Usar Reparo Automatizado

Às vezes, o JSON que você recebe está fora do seu controle — uma resposta de API de um serviço mal construído, um arquivo exportado por software legado ou um trecho colado por um membro de equipe não técnico. Nesses casos, o reparo manual é tedioso e propenso a erros.

Ferramentas de reparo automatizado podem corrigir a maioria dos erros listados acima em uma única passada. Elas analisam a entrada quebrada, inferem a estrutura pretendida e produzem JSON válido. Isso funciona bem para problemas comuns como vírgulas finais, aspas simples e chaves não entre aspas.

A desvantagem é que o reparo automatizado faz suposições. Se o JSON estiver mal formado — faltando grandes seções ou estruturalmente ambíguo — a ferramenta pode adivinhar errado. Sempre valide a saída reparada antes de usá-la em produção.

Experimente você mesmo: Cole JSON quebrado em nossa ferramenta de Reparo de JSON para corrigir automaticamente erros comuns, ou use o Validador de JSON para identificar exatamente onde está o problema.