Cómo solucionar el error «Unexpected token» en JSON.parse: guía práctica sobre todas las causas

SyntaxError: Unexpected token X in JSON at position N es uno de los errores más comunes en JavaScript, y uno de los menos útiles: te indica dónde se ha atascado el analizador, pero no por qué. A continuación te explicamos cómo solucionarlo de verdad.

Paso 1: lee el número de posición

JSON.parse cuenta los caracteres desde el principio de la cadena, empezando por 0. Si tu JSON procede de una variable, registra el fragmento exacto en torno a esa posición antes de hacer nada más:

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

Ese fragmento de código resuelve más errores de este tipo que cualquier consejo sobre la sintaxis JSON, ya que la mayoría de los errores de «token inesperado» son en realidad errores del tipo «no sé qué contiene realmente mi cadena»: espacios en blanco al final por un copiar y pegar, un salto de línea extra de un literal de plantilla o una marca de orden de bytes (BOM) justo al principio (posición 0, token , que es invisible en la mayoría de los editores).

Las 7 causas, clasificadas según la frecuencia con la que se producen realmente

Coma final. {"a": 1, "b": 2,} — válida en literales de objeto de JS, inválida en JSON. La coma antes de } o ] es la causa más común con diferencia.
Comillas simples en lugar de comillas dobles. {'a': 1} es JS, no JSON. JSON requiere comillas dobles tanto alrededor de las claves como de los valores de cadena, sin excepciones.
Claves sin comillas. {a: 1} — de nuevo, válido en JS, no válido en JSON. Todas las claves deben ir entre comillas.
Un valor de JavaScript que no es válido en JSON. undefined, NaN, una función o un comentario ( // like this): ninguno de estos elementos existe en la especificación JSON, solo en JavaScript.
Codificación doble. Has llamado a JSON.stringify() dos veces, o estás analizando una cadena que ya es un objeto — compruébalo con typeof raw === 'string' antes de llamar a .parse().
Una cadena vacía o una respuesta undefined. Si una solicitud ha fallado de forma silenciosa o ha devuelto un cuerpo vacío, JSON.parse("") lanza Unexpected end of JSON input, un error diferente pero relacionado; comprueba response.ok y registra el cuerpo sin procesar antes de analizarlo.
BOM o caracteres invisibles al copiar y pegar. Al pegar JSON desde un PDF, un documento de Word o la salida de algún terminal, puede incluirse un BOM o un espacio no separable que parezca idéntico a un carácter normal.

La solución más rápida: valida antes de depurar

Leer los mensajes de error sin procesar carácter por carácter es lento. Pega la cadena exacta en un formateador que resalte directamente el carácter no válido en lugar de tener que adivinarlo a partir de un número de posición: convierte «en algún lugar cerca del carácter 812» en «este corchete específico que falta, justo aquí» (enlace más abajo).

Cuando el JSON es realmente válido pero sigue fallando

Si un formateador confirma que tu JSON es sintácticamente correcto y JSON.parse sigue dando error, la cadena que estás pasando no es la que crees que es. La razón más habitual: estás llamando a .parse() sobre un objeto Response en lugar de sobre su cuerpo resuelto.

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

Referencia rápida

Síntoma	Causa probable
`Unexpected token }`	Coma al final antes del corchete de cierre
`Unexpected token '`	Se han utilizado comillas simples en lugar de comillas dobles
`Unexpected token a` (o cualquier letra)	Clave de objeto sin comillas
`Unexpected end of JSON input`	Cadena vacía, respuesta truncada o corchete sin cerrar
`Unexpected token` (posición 0)	Marca de orden de bytes procedente de un archivo copiado y pegado o guardado en Windows

Ninguno de estos casos requiere memorizar nada: la solución consiste siempre en los mismos tres pasos: registrar el fragmento en torno a la posición indicada, pasarlo por un formateador y corregir el único carácter que este señale.