Um erro de token inesperado em JSON significa que seu parser encontrou um caractere que não esperava ao ler o que deveria ser um JSON válido. Quase nunca é um bug misterioso. Ele se deve a uma de seis causas concretas: vírgula à direita, aspas simples, uma resposta HTML, um BOM invisível, chaves sem aspas ou comentários. Este guia aborda cada uma e, mais importante, mostra como encontrar a linha e coluna exatas em vez de adivinhar.
A parte frustrante é que a mensagem de erro raramente aponta para o problema real. Token inesperado < em JSON na posição 0 não significa que seu JSON está quebrado. Significa que você não está olhando para JSON. Depois que você aprender a ler o que o parser está dizendo, a maioria dessas correções leva menos de um minuto.
O que "Token Inesperado em JSON" Realmente Significa#
JSON é um formato rigoroso. O analisador lê sua string caractere por caractere e constrói um valor. No momento em que encontra algo que não pode aparecer legalmente naquela posição, ele para e lança um SyntaxError. O "token" é o caractere que causou o erro.
Mecanismos modernos formulam a mensagem de forma diferente, o que aumenta a confusão:
- V8 (Chrome, Node 20+):
Unexpected token 'x', "...contexto..." is not valid JSON - Node / Chrome antigos:
Unexpected token x in JSON at position 42 - Firefox:
JSON.parse: unexpected character at line 2 column 5 of the JSON data - Safari:
JSON Parse error: Unexpected identifier
O campo mais útil é a posição ou o número da linha/coluna. O Firefox fornece linha e coluna diretamente. O V8 fornece uma posição em bytes e um trecho do texto ao redor. Leia isso primeiro, antes de ler qualquer outra coisa.
A maneira mais rápida de transformar uma posição enigmática em um problema visível é colar a string bruta em um validador que destaque a linha com erro. Nosso formatador e validador JSON gratuito marca o ponto exato e informa o que era esperado ali, o que reduz a maior parte da depuração abaixo a uma olhada.
As 6 Causas Reais (e Como Corrigir Cada Uma)#
Aqui está a distribuição honesta. Na depuração do mundo real, a grande maioria desses erros são as causas 1 a 3. As três últimas são mais raras, mas consomem horas porque são invisíveis ou contraintuitivas.
| Causa | Mensagem típica | Indício |
|---|---|---|
| HTML em vez de JSON | Unexpected token < na posição 0 | O primeiro caractere é < (um <!DOCTYPE ou <html>) |
| Vírgula sobressalente | Unexpected token } ou ] | Uma vírgula está antes de uma chave ou colchete de fechamento |
| Aspas simples | Unexpected token ' | Chaves ou strings usam ' em vez de " |
| BOM / caracteres ocultos | Unexpected token na posição 0 em JSON aparentemente válido | Parece perfeito, mas erra logo no início |
| Chaves sem aspas | Unexpected token perto de uma chave | Uma chave como nome: não tem aspas |
| Comentários | Unexpected token / | Existe um comentário // ou /* */ no arquivo |
Causa 1: Você recebeu HTML, não JSON (o caso "token <")#
Esta é a que mais confunde as pessoas, e quase nenhum outro guia explica. Se você vir Unexpected token < in JSON at position 0, o < é a abertura de uma tag HTML. Sua chamada fetch esperava JSON, mas o servidor retornou uma página HTML.
Geralmente significa uma destas:
- O endpoint retornou uma página de erro 404 ou 500 (HTML), não seu payload de API.
- Você acessou a URL errada e recebeu o
index.htmldo aplicativo. - Um proxy, tela de login ou limitador de taxa interceptou a requisição e serviu uma página HTML.
A correção não está no seu JSON. Registre o texto bruto da resposta antes de analisá-lo:
const res = await fetch(url);
const text = await res.text();
console.log(res.status, text.slice(0, 200)); // veja o que você realmente recebeu
const data = JSON.parse(text);
Se text começar com <!DOCTYPE html>, você encontrou. Verifique o código de status e a URL. Confirme também se o Content-Type da resposta é application/json, não text/html.
Causa 2: Vírgula sobressalente#
JSON não permite vírgula após o último item em um objeto ou array. Literais de objeto JavaScript permitem, e é exatamente por isso que isso passa despercebido. Você escreve JSON manualmente da mesma forma que escreve JS, e o analisador rejeita.
{
"nome": "Ada",
"cargo": "engenheira", // esta vírgula sobressalente é inválida
}
Remova a vírgula após "engenheira". O mesmo se aplica a arrays: [1, 2, 3,] é JSON inválido. Um formatador sinaliza isso instantaneamente porque a vírgula ofensiva está logo antes de } ou ].
Causa 3: Aspas simples em vez de aspas duplas#
JSON exige aspas duplas tanto para chaves quanto para valores de string. Aspas simples são um hábito do JavaScript que o JSON não compartilha.
{ 'nome': 'Ada' } // inválido: aspas simples em todo lugar
{ "nome": "Ada" } // válido
Se você controla a fonte, troque cada ' por ". Se a string incorreta veio de algum lugar que você não pode editar, não faça substituição por regex cegamente (apóstrofos dentro de valores quebrarão). Em vez disso, execute-a através de uma ferramenta que entenda a estrutura.
Causa 4: O BOM invisível (e CRLF do Windows)#
Esta engana as pessoas por horas porque o JSON parece perfeito. Você vê JSON válido, cola e o analisador ainda lança erro na posição 0. O culpado é uma marca de ordem de byte, um caractere oculto U+FEFF que alguns editores (e o redirecionamento > do PowerShell no Windows) prefixam em arquivos UTF-8.
O analisador lê o BOM como o primeiro token e o rejeita. Para confirmar, verifique os primeiros bytes:
const text = fs.readFileSync("dados.json", "utf8");
console.log(text.charCodeAt(0)); // 65279 significa que um BOM está presente
const clean = text.replace(/^/, "");
JSON.parse(clean);
Salve o arquivo como UTF-8 sem BOM no seu editor (VS Code mostra a codificação na barra de status; clique e escolha "Salvar com Codificação"). No Windows, prefira Out-File -Encoding utf8NoBOM ou Set-Content em vez do redirecionamento >, que pode injetar o BOM. Retornos de carro soltos de quebras de linha CRLF podem causar estranhezas semelhantes na posição 0 quando JSON é concatenado ou transmitido.
Causa 5: Chaves sem aspas#
Em JavaScript, { nome: "Ada" } é válido. Em JSON, a chave deve ter aspas: { "nome": "Ada" }. Isso acontece mais quando alguém copia um literal de objeto JS para um arquivo .json ou corpo de API.
A correção é colocar aspas duplas em cada chave. Se você tem um objeto grande, um formatador não adicionará aspas automaticamente (isso seria adivinhar sua intenção), mas apontará exatamente a chave que falhou para que você possa corrigi-la rapidamente.
Causa 6: Comentários#
JSON não tem comentários. Nem //, nem /* */. As pessoas os adicionam em arquivos de configuração por hábito e então um analisador rigoroso falha.
{
// configurações do app <- inválido, JSON proíbe comentários
"porta": 3000
}
Remova os comentários. Se você realmente precisa de configuração comentada, use um formato feito para isso (JSON5 ou JSONC, que o VS Code usa para suas próprias configurações) e analise-o com uma biblioteca que suporte esse dialeto, não com JSON.parse simples.
Como Encontrar a Linha e Coluna Exatas do Erro#
Esta é a habilidade que transforma uma caçada de 30 minutos em uma correção de 30 segundos, e é a parte que a maioria dos resultados de pesquisa ignora completamente. O erro fornece uma posição; veja como convertê-la em uma localização real.
Passo 1: Leia a posição ou linha/coluna do erro#
Capture o erro completo, não apenas a primeira palavra. No Node ou no navegador, envolva o parse:
try {
JSON.parse(raw);
} catch (e) {
console.error(e.message); // inclui posição ou linha:coluna
}
O Firefox já fornece linha X coluna Y. O V8 fornece uma posição em bytes. Anote esse número, você o usará a seguir.
Passo 2: Vá para essa posição na string bruta#
Se você tem uma posição em bytes (por exemplo, 142), fatie ao redor dela para ver o contexto que o parser viu:
console.log(raw.slice(130, 160));
O caractere no limite é o seu culpado. Ver 15 caracteres de cada lado quase sempre torna a causa óbvia: uma vírgula solta, uma aspa simples, uma tag HTML.
Passo 3: Cole em um validador que destaca o local#
Examinar posições em uma string longa é lento e propenso a erros. Cole o JSON bruto no formatador e validador JSON, que embeleza a estrutura e marca a linha com erro com uma mensagem clara sobre o que esperava. A própria reformatação muitas vezes revela o problema, pois uma vírgula mal colocada ou um colchete não fechado se torna visualmente óbvio uma vez que o aninhamento está indentado corretamente.
Passo 4: Corrija, revalide e depois teste novamente no código#
Aplique a correção, valide novamente para confirmar que a string agora está limpa e execute seu caminho de código real. Se o JSON veio de uma API, corrija na fonte se possível, em vez de corrigir a string no lado do cliente. Uma resposta limpa supera uma cadeia defensiva de .replace() todas as vezes.
Prevenindo o Erro Antes que Aconteça#
A maioria desses erros pode ser evitada com alguns hábitos. O objetivo é nunca escrever JSON manualmente quando suas ferramentas podem gerá-lo corretamente.
- Nunca construa JSON por concatenação de strings. Use
JSON.stringify()para que as aspas e vírgulas estejam sempre corretas. Se você não tem certeza de como a saída deve ser, nosso guia sobre como formatar JSON em JavaScript abordaJSON.stringifye suas arestas. - Sempre registre a resposta bruta antes de fazer o parse de um resultado de API, para que um
<(HTML) apareça imediatamente em vez de um erro misterioso de token. - Verifique o status HTTP primeiro. Se
res.okfor falso, leia como texto e exiba a página de erro em vez de fazer o parse cegamente. - Salve arquivos de configuração como UTF-8 sem BOM e mantenha um formatador no seu fluxo de trabalho diário. Se você vive em JSON, veja por que o formatador JSON é uma ferramenta diária para desenvolvedores para capturar esses problemas antes de enviá-los.
- Valide seu JSON no CI. Um esquema ou uma etapa simples de parse no seu pipeline detecta uma vírgula à direita antes que ela chegue à produção.
Conclusão: Leia a Posição e Identifique a Causa#
Um erro de token inesperado em JSON parece aleatório até você perceber que é um dos seis problemas previsíveis, e o analisador já lhe disse onde procurar. Comece pela posição ou linha e coluna, depois associe o caractere com falha à causa: < significa HTML, uma vírgula antes de } indica vírgula à direita, um ' significa aspas simples, e um erro na posição 0 em um JSON aparentemente perfeito quase sempre indica um BOM oculto.
Quando quiser parar de apertar os olhos para deslocamentos de bytes, cole a string em um validador que destaque a linha exata e mostre o que era esperado. Esse único passo substitui a maior parte da busca manual e permite que você volte a construir.
Perguntas Frequentes#
O que significa "Unexpected token < in JSON at position 0"?
Significa que a resposta que você tentou analisar começa com um <, que é a abertura de uma tag HTML, não JSON. Seu código esperava JSON, mas o servidor retornou uma página HTML, geralmente uma página de erro 404 ou 500, um redirecionamento de login ou a URL errada. Registre o texto bruto da resposta e verifique o código de status para confirmar.
Por que meu JSON aparentemente válido lança um erro na posição 0?
A causa mais comum é uma marca de ordem de byte (BOM) invisível, um caractere oculto U+FEFF que alguns editores e shells do Windows adicionam a arquivos UTF-8. O JSON parece perfeito, mas o analisador lê o BOM primeiro e o rejeita. Remova-o com text.replace(/^/, "") ou salve o arquivo como UTF-8 sem BOM.
Vírgulas finais são permitidas em JSON?
Não. Uma vírgula após o último item em um objeto ou array é inválida em JSON, embora literais de objeto JavaScript permitam. Esta é uma das causas mais frequentes de erros de token inesperado. Remova a vírgula que está diretamente antes de qualquer } ou ].
Posso usar aspas simples em JSON?
Não. JSON exige aspas duplas para cada chave e cada valor de string. Aspas simples são válidas em JavaScript, mas não em JSON, então { 'nome': 'Ada' } lançará um erro, enquanto { "nome": "Ada" } é analisado corretamente.
Como encontro a linha exata que causa o erro JSON? Leia a posição ou linha e coluna da mensagem de erro primeiro, pois o analisador informa onde falhou. Fatia a string bruta em torno dessa posição para ver o contexto, ou cole a string inteira no formatador e validador JSON para destacar a linha com falha e mostrar qual caractere era esperado ali.
JSON suporta comentários?
JSON puro não suporta comentários de nenhum tipo, então // e /* */ causarão um erro de token inesperado. Se você precisar de configuração comentada, use JSON5 ou JSONC (o dialeto que o VS Code usa para suas configurações) e analise-o com uma biblioteca que entenda esses formatos, em vez de JSON.parse.
