Come risolvere l'errore “Token inatteso” in JSON.parse: una guida pratica a tutte le cause

SyntaxError: Unexpected token X in JSON at position N è uno degli errori più comuni in JavaScript, nonché uno dei meno utili: indica dove il parser si è bloccato, ma non perché. Ecco come risolverlo effettivamente.

Passo 1: leggi il numero di posizione

JSON.parse conta i caratteri dall’inizio della stringa, partendo da 0. Se il tuo JSON proviene da una variabile, registra l’esatto frammento intorno a quella posizione prima di fare qualsiasi altra cosa:

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));
}
}

Questo singolo frammento di codice risolve più errori di questo tipo rispetto a qualsiasi consiglio sulla sintassi JSON, poiché la maggior parte degli errori di “token inatteso” sono in realtà errori del tipo “Non so cosa contenga effettivamente la mia stringa”: spazi finali dovuti a un copia-incolla, un’altra riga a fine di un letterale di template o un byte-order-mark (BOM) proprio all’inizio (posizione 0, token , che è invisibile nella maggior parte degli editor).

Le 7 cause, classificate in base alla frequenza con cui si verificano effettivamente

Virgola finale. {"a": 1, "b": 2,} — valida nei letterali di oggetto JS, non valida in JSON. La virgola prima di } o ] è la causa più comune in assoluto.
Virgolette singole al posto delle doppie. {'a': 1} è JS, non JSON. Il JSON richiede virgolette doppie sia per le chiavi che per i valori stringa, senza eccezioni.
Chiavi senza virgolette. {a: 1} — anche in questo caso, valido in JS, non valido in JSON. Ogni chiave deve essere racchiusa tra virgolette.
Un valore JS non valido in JSON. undefined, NaN, una funzione o un commento ( // like this) — nessuno di questi elementi esiste nelle specifiche JSON, ma solo in JavaScript.
Doppia codifica. Hai chiamato JSON.stringify() due volte, oppure stai analizzando una stringa che è già un oggetto — verifica con typeof raw === 'string' prima di chiamare .parse().
Una stringa vuota o una risposta undefined. Se un’operazione di recupero è fallita silenziosamente o ha restituito un corpo vuoto, JSON.parse("") genera Unexpected end of JSON input, un errore diverso ma correlato — controlla response.ok e registra il corpo grezzo prima dell’analisi.
BOM o caratteri invisibili dovuti al copia-incolla. Incollare JSON da un PDF, un documento Word o l’output di un terminale può comportare la presenza di un BOM o di uno spazio non separabile che appare identico a un carattere normale.

La soluzione più veloce: convalida prima di eseguire il debug

Leggere i messaggi di errore grezzi carattere per carattere è lento. Incolla la stringa esatta in un formattatore che evidenzia direttamente il carattere non valido invece di indovinare in base a un numero di posizione: trasforma «da qualche parte vicino al carattere 812» in «questa specifica parentesi mancante, proprio qui». (Link in basso.)

Quando il JSON è effettivamente valido ma continua a generare un errore

Se un formattatore conferma che il tuo JSON è sintatticamente corretto e JSON.parse continua a generare un errore, la stringa che stai passando non è quella che pensi sia. Il motivo più comune: stai chiamando .parse() su un oggetto Response anziché sul suo corpo risolto.

// 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);

Riferimento rapido

Sintomo	Causa probabile
`Unexpected token }`	Virgola finale prima della parentesi graffa di chiusura
`Unexpected token '`	Utilizzo di virgolette singole al posto delle doppie
`Unexpected token a` (o qualsiasi lettera)	Chiave dell’oggetto non racchiusa tra virgolette
`Unexpected end of JSON input`	Stringa vuota, risposta troncata o parentesi non chiusa
`Unexpected token` (posizione 0)	Byte-order-mark proveniente da un file copiato e incollato o salvato su Windows

Nessuna di queste situazioni richiede di memorizzare nulla: la correzione consiste sempre negli stessi tre passaggi: registrare lo slice intorno alla posizione segnalata, elaborarlo con un formattatore, correggere l’unico carattere segnalato.