O JSON falha ao ser lido porque algo no texto não está na gramática, e os suspeitos de sempre são uma vírgula sobrando no fim, aspas simples, uma chave sem aspas, um comentário ou um byte order mark invisível logo no começo. A mensagem de erro nomeia o caractere em que o parser desistiu. Esse caractere está no erro ou logo depois dele, nunca antes, porque um parser lê da esquerda para a direita e tudo o que ele já passou ainda era válido.
As mensagens abaixo vêm do Node 22, que usa o mesmo motor de JavaScript do Chrome. Firefox e Safari as redigem de outro jeito, então trate o texto exato como exemplo e a posição como a parte útil.
O que o erro diz para cada engano e para onde ele aponta?
| O que você escreveu | O que a mensagem diz | Para onde aponta |
|---|---|---|
{"a":1,} | Esperava-se um nome de propriedade entre aspas duplas | A chave de fechamento, um caractere depois da vírgula |
[1,2,] | Token ']' inesperado | O colchete de fechamento, sem nenhuma posição |
{'a':1} ou {a:1} | Esperava-se um nome de propriedade ou '}' | O primeiro caractere da chave |
{"a":1 // nota} | Esperava-se ',' ou '}' depois do valor da propriedade | A primeira barra |
| Um arquivo salvo com byte order mark | Token inesperado, mostrado como um par de aspas de aparência vazia | O primeiro caractere, sem posição |
A localização costuma ser honesta. O que engana é a redação, porque o parser descreve o que esperava, não o que você quis dizer.
Por que a culpa de uma vírgula sobrando cai no colchete?
Depois de uma vírgula, a gramática exige outro valor ou outro membro. Quando o parser encontra } ou ] no lugar, é ali que ele para. A vírgula que aceitou um instante antes estava correta pelo que ele sabia, então o relato cai no caractere de fechamento e o erro é o caractere anterior.
A mensagem muda conforme o contêiner. Em um objeto, diz que esperava um nome de propriedade entre aspas duplas. Em um array, diz apenas que o colchete era inesperado, e nesse caso o formatador deste site mostra a mensagem sem linha e coluna, porque ela não traz posição para ler. Procure uma vírgula logo antes da primeira chave ou colchete de fechamento que você achar perto de onde o arquivo começa a dar problema.
Vírgulas sobrando são legais em JavaScript, e é por isso que se escrevem. Não são JSON válido, e nenhum parser estrito as aceita.
Por que aspas simples e chaves sem aspas dão a mesma mensagem?
As duas quebram a mesma regra: a chave de um objeto precisa ser uma string entre aspas duplas. Uma chave entre aspas simples e uma chave sem aspas começam com um caractere que o parser não esperava naquela posição, então ele informa a mesma coisa. A mensagem diz que esperava um nome de propriedade, o que soa absurdo quando você está vendo um ali mesmo.
A correção é mecânica para as chaves e arriscada para os valores. Um valor entre aspas simples gera outra mensagem (um token inesperado, sem posição no Chrome), e um localizar e substituir global de ' por " vai estragar qualquer string que tenha um apóstrofo. Corrija primeiro as chaves e depois os valores, olhando um a um. Se o texto saiu de um print do Python ou de um objeto literal do JavaScript, serialize direito na origem.
Por que um comentário faz o erro dizer que esperava uma vírgula?
Um valor acabou de terminar, então o parser procura uma vírgula ou uma chave de fechamento. Ele encontra uma barra e relata isso, sem dizer nada sobre comentários. A posição é exata: aponta para a primeira barra do comentário.
O formato não tem sintaxe de comentário porque ela foi removida de propósito. Por que o JSON não tem comentários conta quem os tirou e quais arquivos de configuração leem um dialeto mais flexível mesmo assim. O teste prático é que o tsconfig.json tolera comentários e o package.json não, então a extensão do arquivo não diz nada.
Por que um arquivo que parece certo falha no primeiro caractere?
Um byte order mark é o caractere U+FEFF no começo de um arquivo; alguns editores o gravam quando você salva como «UTF-8 com BOM». Ele não aparece, então o arquivo parece perfeito, e o parser vê um caractere que não é espaço em branco nem um valor. A RFC 8259 diz que quem gera JSON não deve incluí-lo em textos enviados pela rede e que um parser pode ignorá-lo em vez de tratá-lo como erro. O JSON.parse do Chrome não o ignora.
A pista é a mensagem: um token inesperado seguido de um par de aspas sem nada visível no meio, e sem posição. Se você vir isso, o problema não está no texto que você consegue ler. Apague o primeiro caractere ou salve o arquivo de novo como UTF-8 simples, sem BOM.
Na mesma família entram um espaço sem quebra depois da última chave, que volta como «caractere inesperado que não é espaço em branco depois do JSON», e aspas tipográficas coladas de um documento. Caracteres invisíveis em um texto mostra como achar o primeiro caso, e por que o texto colado do Word dá errado cobre o segundo.
Como achar o erro quando a mensagem não ajuda?
Cole o texto no formatador de JSON. Quando a mensagem do navegador inclui uma posição, a ferramenta a converte em linha e coluna, que é bem mais fácil de usar do que um deslocamento de caracteres. Corrija esse erro, cole de novo e espere outro: o parser só relata o primeiro problema, então um arquivo com seis erros leva seis rodadas.
Se o arquivo é grande, está minificado ou a mensagem não traz posição, parta-o ao meio:
- Fique com tudo até um ponto em que um membro ou elemento completo acabou de terminar. Apague o resto.
- Feche à mão os colchetes e chaves que ficaram abertos.
- Se ele for lido, a falha está na metade que você tirou. Se ainda falhar, está na que você manteve, e essa você parte de novo.
Cada rodada reduz a busca pela metade, então um arquivo com alguns milhares de registros leva cerca de uma dúzia de tentativas. Em um array de registros no nível superior é ainda mais rápido apagar registros a partir do fim até o erro sumir. O primeiro registro que o trouxer de volta é o culpado. O guia de JSON minificado tem a versão de contar colunas para um arquivo que está todo em uma linha só.
O que o formatador não consegue dizer?
Ele diz que o arquivo não é JSON válido e, quando o navegador fornece uma posição, onde parou. Não sugere correção e não conserta nada. Também não distingue um erro nos seus dados de um arquivo que nunca foi JSON: JSON5, JSONC e logs de um objeto por linha falham do mesmo jeito, como dizem as notas do próprio formatador. A redação e a presença de uma posição dependem do navegador em que você o executa, então a mesma entrada pode dar uma mensagem um pouco diferente em outro.
Tudo roda na aba. O texto não é enviado a lugar nenhum, o que importa quando o arquivo é uma configuração com um token dentro.
Quando o erro é uma posição que você não consegue interpretar, o formatador de JSON a transforma em linha e coluna e roda inteiro no seu navegador, então uma configuração com credenciais fica na sua máquina.
Se a causa acabou sendo um comentário que você tinha certeza de que deveria ser permitido, por que o JSON não tem comentários explica a história e o que usar no lugar.
Perguntas frequentes
Por que o JSON.parse diz «unexpected token» sem nenhuma posição?
Nos motores da família do Chrome, alguns erros (uma vírgula sobrando em um array, um valor entre aspas simples, NaN, um byte order mark) informam apenas o token inesperado e uma cópia da entrada, sem posição. O texto continua inválido nesse token ou antes dele. Trabalhe a partir do começo do texto, ou parta a entrada ao meio até o erro sumir.
Vírgula sobrando é permitida em JSON?
Não. A gramática admite uma vírgula apenas entre dois valores ou membros, então uma vírgula antes de um colchete ou chave de fechamento é erro de sintaxe em qualquer parser estrito. Objetos literais do JavaScript e alguns dialetos como o JSON5 a aceitam, e por isso ela é escrita tantas vezes por engano.
Por que meu arquivo JSON falha se parece totalmente válido?
Verifique os caracteres que você não vê. Um byte order mark no começo do arquivo, um espaço sem quebra ou aspas tipográficas coladas de um documento parecem texto válido e fazem a leitura falhar. Salvar de novo como UTF-8 simples sem BOM e redigitar os caracteres suspeitos costuma resolver.
Como encontro o erro em um arquivo JSON muito grande?
Corrija o primeiro erro relatado e leia de novo, porque o parser para no primeiro problema. Se a posição não servir, corte o arquivo em um registro completo, feche os colchetes e teste cada metade. A metade que falha contém a falha, e repetir o corte a reduz rápido.
Um byte order mark torna um JSON inválido?
A RFC 8259 diz que um texto JSON enviado pela rede não deve começar com um, e que um parser pode ignorá-lo em vez de tratá-lo como erro. «Pode» significa que alguns fazem isso e outros não, e o JSON.parse do Chrome o rejeita. O mais seguro é um arquivo sem ele.
Última atualização 4 de novembro de 2026
