Como corrigir JSON inválido: cada erro comum explicado

O JSON é rígido de um jeito que parece implicância até você conhecer as regras. Sem vírgula no final. Só aspas duplas. Sem comentários. As chaves precisam estar entre aspas. Quebre qualquer uma delas, em qualquer lugar, e o documento inteiro é rejeitado, com uma mensagem que aponta uma posição de caractere e raramente diz o que está errado.

Esta página liga as mensagens de erro às causas, e as causas às correções.

A resposta rápida

1. Encontre a posição. Todo parser informa uma linha e uma coluna, ou um deslocamento em caracteres. Vá até lá; o erro está nesse ponto ou logo antes.
2. Procure os cinco de sempre: uma vírgula no final, aspas simples, uma chave sem aspas, um comentário ou uma vírgula faltando entre dois itens.
3. Se o erro estiver na posição 0 ou na linha 1, coluna 1, o problema não é o JSON. Você recebeu outra coisa: uma página de erro HTML, uma resposta vazia ou uma marca de ordem de bytes (BOM).

Para obter a localização exata em qualquer máquina:

python3 -m json.tool broken.json
jq . broken.json

Como ler a mensagem de erro

O mesmo erro aparece de forma diferente em cada linguagem. Ache a sua e depois a causa:

As causas, uma por uma

Vírgula no final

{ "name": "Ada", "role": "admin", }

Permitida em código JavaScript, proibida em JSON. O parser chega ao } esperando outra chave. Apague a última vírgula. Arquivos de configuração editados à mão e código que monta JSON concatenando strings são as fontes mais comuns.

Aspas simples

{ 'name': 'Ada' }

Strings JSON sempre usam aspas duplas. Isso costuma vir de um dict do Python exibido com print() em vez de json.dumps(). A correção de verdade está no código que o gerou: serialize com uma biblioteca JSON, não com formatação de strings.

Chaves sem aspas

{ name: "Ada" }

JavaScript válido, JSON inválido. Coloque aspas em todas as chaves.

Comentários

{ "port": 8080 // default }

JSON não tem comentários. Mas cuidado antes de "consertar": alguns arquivos foram feitos para tê-los. tsconfig.json, o settings.json do VS Code e muitos outros arquivos de configuração são JSONC (JSON com comentários) ou JSON5, e as ferramentas que os leem aceitam comentários. Se o arquivo for um desses, o problema é o parser rígido para o qual você o está enviando, não o arquivo.

Uma vírgula faltando

{ "a": 1 "b": 2 }

O parser reporta em "b", que fica depois do erro. Quando o erro aponta para uma chave perfeitamente boa, olhe o final da linha anterior.

Valores que o JSON não tem

NaN, Infinity, undefined e números com zeros à esquerda, como 007, são todos inválidos. Um número hexadecimal, 0xFF, também. Use null, uma string ou um decimal simples, conforme o que o leitor espera.

Quebras de linha e tabulações literais dentro de uma string

Uma string precisa escapar as quebras de linha como \n e as tabulações como \t. Uma quebra de linha real entre aspas é inválida. Isso costuma acontecer quando um valor de várias linhas é colado à mão num arquivo JSON.

Barras invertidas

Um caminho do Windows como "C:\new\folder" quebra, porque \n e \f são sequências de escape. Duplique cada barra invertida, "C:\\new\\folder", ou use barras normais.

Aspas curvas

“name” parece uma string, mas não é: são aspas tipográficas, não ". Elas vêm de JSON copiado de um documento, de um aplicativo de chat ou de um slide, ou de digitar no iPhone ou iPad, onde a Pontuação Inteligente troca as aspas retas enquanto você digita. Desative em Ajustes → Geral → Teclado antes de editar JSON no iOS.

Erros na "posição 0": não é JSON

Quando o erro está no primeiro caractere, o conteúdo está errado, não a sintaxe.

• < na posição 0 significa que você analisou HTML. O servidor devolveu uma página de erro, uma página de login ou um 404, e seu código tentou lê-la como JSON. Registre a resposta bruta e o código de status antes de analisar.
• Entrada vazia significa que a resposta não tinha corpo, geralmente um 204 No Content ou uma requisição que falhou antes de o servidor responder.
• Um caractere invisível no início costuma ser uma marca de ordem de bytes UTF-8 adicionada por um editor do Windows. No Python, abra o arquivo com encoding="utf-8-sig"; em outros casos, salve-o de novo como UTF-8 sem BOM.

NDJSON não é JSON quebrado

Um arquivo com um objeto JSON por linha (.jsonl, .ndjson ou saída de logs) falha com "Extra data" ou "Unexpected non-whitespace" no início da linha dois. Cada linha é válida sozinha. Analise linha por linha, ou use uma ferramenta que entenda o formato: jq -c . file.jsonl lê todas as linhas.

Reparando automaticamente

Para os deslizes comuns (vírgulas no final, aspas simples, chaves sem aspas, comentários), o reparo automático é seguro porque só existe um significado razoável. Ferramentas que fazem isso:

• jsonrepair, uma biblioteca JavaScript e ferramenta de linha de comando.
• A maioria dos editores de código, por meio de uma extensão de JSON5 ou "fix JSON".
• Um app editor de JSON que valida enquanto você digita.

O reparo automático não é seguro para um arquivo truncado. Uma ferramenta de reparo fecha os colchetes abertos e entrega um documento válido, mas com dados faltando. Busque ou exporte o arquivo de novo.

No iPhone e no iPad, o Smart Json mostra o erro em linguagem simples, com linha e coluna. Go leva o cursor até ele, e Fix repara comentários, vírgulas no final, aspas simples e chaves sem aspas com um toque.

JSON Editor: Smart JsoniPhone e iPad

Nomeia um erro de JSON em palavras simples, com linha e coluna, pula até ele e repara comentários, vírgulas no final, aspas simples e chaves sem aspas com um toque.

O que ele faz

Como não quebrar o JSON logo de início

Quase todo arquivo JSON inválido foi escrito à mão ou montado com concatenação de strings. Gere JSON com um serializador (json.dumps, JSON.stringify, JSONEncoder) e valide os arquivos editados à mão antes de fazer commit. Um hook de pre-commit rodando jq . file.json > /dev/null pega tudo isso antes que outra pessoa veja.