Erro de parse JSON: causas comuns e como corrigir

A maioria dos erros de parse de JSON vem de uma lista curta de equívocos: vírgula sobrando no final, string entre aspas simples, comentário, chave sem aspas, valor como NaN ou undefined, ou aspas curvas copiadas de um documento. O JSON é mais rigoroso que o JavaScript de que se parece, então um código que parece correto para uma pessoa pode ser rejeitado pelo parser. A mensagem de erro indica uma linha e uma coluna, e a correção costuma estar nesse ponto ou logo antes dele.

Formatar JSONJSON não é lido (erro de sintaxe)Use de graça

As regras que o JSON exige

Um documento JSON é um único valor: um objeto entre chaves, um array entre colchetes, uma string, um número, true, false ou null. Dentro desses valores:

Toda chave e toda string usa aspas duplas retas, como "name".
Vírgulas separam os itens, e não pode haver vírgula depois do último item de um objeto ou array.
Números não podem ter sinal de mais no início, e NaN, Infinity e undefined não são números nem valores válidos.
Comentários não são permitidos de forma alguma.
Chaves precisam ser strings, então uma chave sem aspas, como name:, é inválida.

Alguns parsers aceitam alguns desses casos por padrão, e algumas ferramentas aceitam JSON com comentários por conveniência. Essa tolerância esconde o problema até o arquivo chegar a um leitor mais rigoroso, então escreva na forma estrita.

Como ler a mensagem de erro

Os parsers informam o primeiro ponto em que não conseguiram continuar. A mensagem nomeia o problema e indica uma posição, geralmente uma linha e uma coluna. Veja um arquivo pequeno com uma vírgula sobrando em um array e outra depois da última propriedade:

{
  "name": "Ada",
  "tags": ["a", "b",],
}

O Python informa isso como "Illegal trailing comma before end of array: line 3 column 20". A redação muda de ferramenta para ferramenta, e alguns parsers mais antigos dizem apenas "Unexpected token" com um deslocamento de caractere. Vá até a posição indicada e olhe o caractere logo antes dela. O erro real costuma ser uma vírgula, aspa ou chave um ou dois caracteres antes do ponto informado.

Mais algumas mensagens do parser do Python e o que costumam significar:

"Expecting property name enclosed in double quotes" para '{'a': 1}' indica uma chave com aspas simples ou sem aspas.
"Expecting value" em uma posição onde você esperava um número ou string costuma indicar uma aspa curva, já que o parser a vê como um caractere desconhecido.
"Expecting ',' delimiter" geralmente indica uma vírgula faltando entre dois itens, ou um comentário no meio dos dados.

Aspas curvas e texto copiado

As aspas curvas são o caso mais confuso, porque quase não se diferenciam das aspas retas. Um arquivo JSON copiado de um editor de texto, de uma página da web ou de uma mensagem de chat pode conter aspas duplas curvas. Para você, o arquivo parece correto, mas falha no parse, porque o parser vê “x” como um caractere desconhecido em vez de um delimitador de string.

Caracteres ocultos causam o mesmo tipo de falha. Um espaço não separável entre dois valores não é um espaço em branco para o parser. Remover caracteres ocultos antes de tentar consertar a estrutura à mão e, depois, corrija as aspas. O guia de aspas curvas explica como endireitá-las com segurança.

Aspas simples, comentários e chaves sem aspas

Muitos desenvolvedores escrevem dados semelhantes a JSON em uma linguagem que permite mais coisas:

Aspas simples são válidas em literais de JavaScript e Python, mas o JSON exige aspas duplas. Substitua {'a': 1} por {"a": 1}.
Comentários como // ou /* */ precisam ser removidos. Se você precisa de notas, coloque-as em um campo separado ou use um formato feito para arquivos de configuração.
Chaves sem aspas são comuns em objetos literais do JavaScript. Coloque as aspas.
NaN e undefined não fazem parte do JSON. Use null para um valor ausente ou uma string se o valor for texto.

Cuidado com a substituição geral. Trocar cada aspa simples por uma aspa dupla quebra qualquer string que contenha um apóstrofo, como "Ada's notes". Antes de tudo, visualize cada ocorrência em Localizar e substituir para ver quais aspas seriam alteradas.

Corrija a estrutura passo a passo

Cole o arquivo em Formatar JSON. Formatá-lo torna a estrutura visível, e o erro mostra a linha e a coluna. Depois, clique em Reparar, que remove comentários e vírgulas sobrando. Ele não altera aspas simples nem aspas curvas, então corrija essas por conta própria.
Corrija apenas o primeiro erro e verifique de novo. Um único equívoco pode gerar vários erros mais adiante.
Confira se toda chave ou colchete de abertura tem o de fechamento correspondente e se o aninhamento é o que você pretende.
Valide o arquivo final com o parser que sua aplicação usa, e não apenas com uma ferramenta web. Os parsers diferem um pouco entre si.

Um arquivo que passa no parse não é necessariamente o arquivo que você queria. Confira-o com o Validador de JSON Schema para encontrar um campo faltando ou um valor do tipo errado, ou compare dois documentos JSON para ver o que mudou entre as versões.

Casos especiais

Vírgulas sobrando em arquivos gerados. Algumas ferramentas as escrevem. Se você monta o JSON à mão, concatenando strings, use o serializador da sua linguagem, que gera uma saída válida.
Chaves duplicadas. O JSON as permite, mas a maioria dos parsers mantém apenas o último valor. Chaves duplicadas são um bug esperando para acontecer.
Números grandes. Inteiros muito grandes podem perder precisão em alguns parsers, então guarde identificadores como strings se forem maiores do que o parser consegue representar com exatidão. O guia de CSV para JSON faz o mesmo alerta sobre IDs.

Respostas rápidas

Por que meu JSON falha se parece correto?

As causas mais comuns são vírgula sobrando, aspas simples, comentário ou aspas curvas copiadas de um documento. Verifique a posição na mensagem de erro e o caractere logo antes dela.

O JSON pode ter comentários?

Não. O padrão JSON não permite comentários. Remova-os ou mova as notas para um campo próprio. O botão Reparar do formatador os remove para você.

O que usar no lugar de undefined no JSON?

Use null quando um valor estiver ausente de propósito, ou omita a chave por completo. undefined é um valor do JavaScript e não tem representação em JSON.

Os erros de JSON por trás da maioria dos erros de parse, e como corrigi-los