Resolver o erro «Token inesperado» no JSON.parse: um guia prático sobre todas as causas

O SyntaxError: Unexpected token X in JSON at position N é um dos erros mais comuns em JavaScript e um dos menos úteis — indica-lhe onde o analisador desistiu, mas não porquê. Eis como resolver o problema de facto.

Passo 1: leia o número da posição

O JSON.parse conta os caracteres a partir do início da cadeia de caracteres, começando em 0. Se o seu JSON vier de uma variável, registe o trecho exato em torno dessa posição antes de fazer qualquer outra coisa:

try {
JSON.parse(raw);
} catch (e) {
const match = e.message.match(/position (\d+)/);
if (match) {
const pos = Number(match[1]);
console.log(raw.slice(Math.max(0, pos - 20), pos + 20));
}
}

Esse pequeno trecho de código resolve mais erros deste tipo do que qualquer conselho sobre a sintaxe JSON, porque a maioria dos erros de «token inesperado» são, na verdade, erros do tipo «não sei o que a minha cadeia de caracteres contém realmente» — espaços em branco finais resultantes de um copiar-colar, uma nova linha extra de um literal de modelo ou uma marca de ordem de bytes (BOM) logo no início (posição 0, token , que é invisível na maioria dos editores).

As 7 causas, classificadas pela frequência com que realmente ocorrem

Vírgula final. {"a": 1, "b": 2,} — válida em literais de objeto JS, inválida em JSON. A vírgula antes de } ou ] é a causa mais comum.
Aspas simples em vez de aspas duplas. {'a': 1} é JS, não JSON. O JSON exige aspas duplas à volta tanto das chaves como dos valores de cadeia de caracteres, sem exceções.
Chaves sem aspas. {a: 1} — mais uma vez, válido em JS, inválido em JSON. Todas as chaves precisam de aspas.
Um valor JS que não é JSON válido. undefined, NaN, uma função ou um comentário ( // like this) — nenhum destes existe na especificação JSON, apenas em JavaScript.
Codificação dupla. Chamou JSON.stringify() duas vezes, ou está a analisar uma cadeia de caracteres que já é um objeto — verifique com typeof raw === 'string' antes de chamar .parse().
Uma cadeia de caracteres vazia ou uma resposta undefined. Se uma chamada de dados falhar silenciosamente ou devolver um corpo vazio, JSON.parse("") lança Unexpected end of JSON input, um erro diferente mas relacionado — verifique response.ok e registe o corpo bruto antes de analisar.
BOM ou caracteres invisíveis resultantes de copiar e colar. Colar JSON a partir de um PDF, documento do Word ou de alguma saída de terminal pode incluir um BOM ou um espaço não separável que parece idêntico a um caractere normal.

A solução mais rápida: valide antes de depurar

Ler mensagens de erro em bruto, caractere a caractere, é demorado. Cole a cadeia de caracteres exata num formatador que destaque diretamente o caractere inválido, em vez de adivinhar a partir de um número de posição — isso transforma «algures perto do caractere 812» em «este parêntese específico que falta, mesmo aqui». (Link abaixo.)

Quando o JSON é genuinamente válido, mas continua a falhar

Se um formatador confirmar que o seu JSON está sintaticamente correto e o JSON.parse continuar a lançar um erro, a cadeia de caracteres que está a passar não é aquela que pensa que é. A razão mais comum: está a chamar o .parse() num objeto Response em vez de no seu corpo resolvido.

// Wrong — parses "[object Response]", not the body
const data = JSON.parse(await fetch(url));

// Right
const data = await (await fetch(url)).json();
// or, if you need the raw text first:
const text = await (await fetch(url)).text();
const data = JSON.parse(text);

Referência rápida

Sintoma	Causa provável
`Unexpected token }`	Vírgula final antes da chave de fecho
`Unexpected token '`	Utilização de aspas simples em vez de aspas duplas
`Unexpected token a` (ou qualquer letra)	Chave de objeto sem aspas
`Unexpected end of JSON input`	String vazia, resposta truncada ou parêntese não fechado
`Unexpected token` (posição 0)	Marca de ordem de bytes proveniente de um arquivo copiado e colado ou guardado no Windows

Nenhuma destas situações requer que se memorize nada — a correção consiste sempre nos mesmos três passos: registar a fatia em torno da posição indicada, submetê-la a um formatador e corrigir o único carácter que este assinalar.