Si alguna vez ha trabajado con JSON, es casi seguro que se ha topado con el temido mensaje SyntaxError: Unexpected token. Aparece en las consolas del navegador, en las respuestas de las API, en los archivos de configuración y en los pipelines de CI/CD. El error en sí no es muy útil: le indica que algo está mal, pero rara vez explica qué.
Esta guía repasa las causas más comunes de los errores de análisis de JSON, le muestra exactamente cómo corregir cada una y le ofrece un flujo de trabajo fiable para detectar estos fallos antes de que provoquen problemas. Si quiere ir directamente a una solución, pegue su JSON defectuoso en el JSON Formatter y este resaltará la línea y el carácter exactos donde se produce el error.
¿Qué significa realmente "Unexpected token"?
Los analizadores de JSON leen su texto carácter por carácter. Cuando el analizador encuentra un carácter que no corresponde según la especificación de JSON, lanza un SyntaxError. El "unexpected token" es simplemente el carácter que el analizador no esperaba encontrar en esa posición.
Por ejemplo, si el analizador espera comillas dobles para iniciar un valor de cadena pero encuentra comillas simples en su lugar, informa algo como esto:
SyntaxError: Unexpected token ' in JSON at position 14
El número de posición le indica cuántos caracteres desde el principio de la cadena alcanzó a leer el analizador antes de rendirse. Esto es útil, pero contar caracteres manualmente en un archivo JSON grande resulta tedioso. Ahí es donde una herramienta como el JSON Formatter se vuelve indispensable: localiza la ubicación del error de forma visual.
Las 5 causas más comunes de los errores de análisis de JSON
1. Comas finales
Esta es posiblemente la causa más frecuente de los errores de análisis de JSON, sobre todo para quienes escriben JavaScript con regularidad. Los arreglos y objetos de JavaScript aceptan sin problema las comas finales. JSON no.
La versión defectuosa:
{
"name": "Alice",
"age": 30,
"city": "Tokyo",
}
La versión corregida:
{
"name": "Alice",
"age": 30,
"city": "Tokyo"
}
La coma que sigue a "Tokyo" es el problema. El analizador de JSON lee la coma, espera otro par clave-valor y, en su lugar, encuentra una llave de cierre. Esa llave de cierre se convierte en el "unexpected token".
Las comas finales también aparecen en los arreglos:
{
"colors": ["red", "green", "blue",]
}
Elimine la coma que sigue a "blue" y el error desaparece:
{
"colors": ["red", "green", "blue"]
}
Este fallo es tan fácil de cometer que muchos editores de código ahora tienen ajustes para eliminar automáticamente las comas finales al guardar archivos JSON. Si su editor lo admite, active esa función.
2. Comillas simples en lugar de comillas dobles
JSON requiere comillas dobles para todas las cadenas y claves. Las comillas simples no son válidas, aunque tanto JavaScript como Python las acepten para los literales de cadena.
La versión defectuosa:
{
'name': 'Alice',
'age': 30
}
La versión corregida:
{
"name": "Alice",
"age": 30
}
Este error suele aparecer cuando alguien copia un diccionario de Python o un objeto literal de JavaScript e intenta usarlo como JSON. Los dos formatos se parecen, pero no son intercambiables.
Una búsqueda y reemplazo rápido de ' por " suele funcionar, pero tenga cuidado si los valores de sus cadenas contienen apóstrofos. En ese caso, deberá escaparlos o gestionar el reemplazo con más cuidado. Pegar el texto en el JSON Formatter marcará las posiciones exactas donde aparecen las comillas simples para que pueda corregirlas una por una.
3. Claves sin comillas
En JavaScript, las claves de los objetos no necesitan comillas si son identificadores válidos. En JSON, cada clave debe ser una cadena entre comillas dobles, sin excepciones.
La versión defectuosa:
{
name: "Alice",
age: 30
}
La versión corregida:
{
"name": "Alice",
"age": 30
}
Esto tiende a ocurrir cuando alguien escribe JSON a mano o lo copia desde una fuente de JavaScript. También aparece en archivos de configuración donde alguien ha olvidado que JSON es más estricto que el lenguaje que utiliza habitualmente.
4. Comentarios en JSON
JSON no admite comentarios. Ni comentarios de una sola línea (//), ni comentarios de varias líneas (/* */), ni comentarios con almohadilla (#). Si un analizador encuentra cualquiera de estos, lanza un error.
La versión defectuosa:
{
// User's display name
"name": "Alice",
/* Age in years */
"age": 30
}
La versión corregida:
{
"name": "Alice",
"age": 30
}
Este es un verdadero punto de fricción. Es perfectamente razonable querer comentarios en un archivo de configuración, y muchos desarrolladores se frustran porque JSON no los permite. Algunas herramientas (como el settings.json de VS Code) en realidad usan un superconjunto llamado JSONC (JSON con comentarios), pero los analizadores de JSON estándar rechazan los comentarios de plano.
Para una comparación lado a lado de JSONC, JSON5, los campos _comment y los scripts de eliminación, y cuál elegir para archivos de configuración, datos o API, consulte ¿Puede JSON tener comentarios?. Si prefiere dejar JSON por completo, YAML admite comentarios de forma nativa con el carácter # y puede convertir fácilmente entre ambos formatos. Eche un vistazo a nuestro artículo de consejos de formato de JSON para saber más sobre cómo gestionar archivos JSON complejos.
5. Caracteres BOM (Byte Order Mark)
Este es engañoso porque no se puede ver el problema con solo mirar el archivo. Un BOM es un carácter invisible (U+FEFF) que algunos editores de texto, especialmente en Windows, insertan justo al principio de un archivo. Le indica al editor qué codificación utiliza el archivo.
El analizador de JSON se topa con este carácter invisible antes de llegar al { o [ de apertura y no tiene ni idea de qué hacer con él. El mensaje de error podría verse así:
SyntaxError: Unexpected token in JSON at position 0
Ese espacio que parece en blanco antes de "in JSON" es el carácter BOM.
Cómo corregirlo:
- Abra el archivo en un editor hexadecimal y elimine los tres primeros bytes (
EF BB BFpara el BOM de UTF-8). - En VS Code, haga clic en el indicador de codificación de la barra de estado, elija "Save with Encoding" y seleccione "UTF-8" (sin BOM).
- Use una herramienta de línea de comandos:
sed -i '1s/^\xEF\xBB\xBF//' file.json
El estado antes (mostrado en hexadecimal):
EF BB BF 7B 0A 20 20 22 6E 61 6D 65 22 ...
El estado después:
7B 0A 20 20 22 6E 61 6D 65 22 ...
El contenido del archivo se ve idéntico en un editor de texto, pero ahora el analizador puede leerlo.
Otras causas que conviene conocer
Más allá de las cinco principales, aquí tiene algunos problemas adicionales que hacen tropezar a la gente:
Corchetes o llaves descompensados
La falta de un } o ] de cierre provocará un error de análisis, que normalmente se informa al final del archivo. Si su JSON está profundamente anidado, encontrar el corchete descompensado a simple vista es casi imposible. Un formateador con emparejamiento de corchetes le ahorrará mucho tiempo.
Caracteres de control en las cadenas
Los saltos de línea, las tabulaciones y otros caracteres de control dentro de las cadenas de JSON deben escaparse. Un salto de línea literal dentro del valor de una cadena no es válido:
{"message": "Hello
World"}
Debería ser:
{"message": "Hello\nWorld"}
Números con ceros a la izquierda
Los números de JSON no pueden tener ceros a la izquierda. 007 no es JSON válido: debe ser 7, 0.07 o algún otro formato numérico estándar.
{
"code": 007
}
Corregido:
{
"code": 7
}
Uso de undefined o NaN
Los valores undefined y NaN de JavaScript no son valores válidos de JSON. Si serializa un objeto que contiene undefined, la mayoría de los serializadores omitirán la clave o lanzarán un error. NaN e Infinity se rechazan de forma similar.
Un flujo de trabajo fiable para depurar JSON
Cuando se encuentra con un error de análisis y el archivo tiene más de unas pocas líneas, mirar fijamente el texto en bruto no es productivo. Aquí tiene un flujo de trabajo que funciona de forma consistente:
-
Pegue el JSON en el JSON Formatter. Le mostrará la ubicación exacta del error con un número de línea y una descripción de lo que salió mal.
-
Observe la posición informada. El error suele estar en la posición que informa el analizador, o justo antes. A veces, el error real se encuentra unas líneas antes: por ejemplo, una coma faltante en la línea 10 podría no provocar un error hasta que el analizador llega a la línea 11.
-
Compruebe las cinco causas principales enumeradas arriba. En la práctica, las comas finales y las comillas simples representan la mayoría de los errores de análisis del mundo real.
-
Si el archivo fue generado por código, revise el paso de serialización. ¿Está usando
JSON.stringify()o una función equivalente? Construir cadenas JSON a mano con concatenación de cadenas es una fuente habitual de errores. -
Si el archivo se descargó o se recibió desde una API, compruebe la codificación. Los problemas de BOM, las discrepancias en la codificación de caracteres y las respuestas truncadas producen errores de análisis.
Errores de análisis en distintos entornos
Los mensajes de error varían según la plataforma, lo que puede dificultar la búsqueda de soluciones.
En el navegador (Chrome, Firefox):
SyntaxError: Unexpected token < in JSON at position 0
Este error en particular —< inesperado en la posición 0— casi siempre significa que el servidor devolvió una página de error HTML en lugar de JSON. Revise la pestaña de red para ver qué devolvió realmente la API.
En Node.js:
SyntaxError: Unexpected token } in JSON at position 142
Node le da un número de posición que puede usar para localizar el problema.
En Python:
json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes: line 3 column 5
Python es bastante útil en realidad: le da tanto el número de línea como el número de columna.
En Java (Jackson):
com.fasterxml.jackson.core.JsonParseException: Unexpected character ('}' (code 125)): was expecting double-quote to start field name
Jackson es prolijo, pero específico sobre lo que esperaba frente a lo que encontró.
Cómo prevenir los errores de análisis desde el principio
En lugar de corregir los errores a posteriori, unos cuantos hábitos pueden eliminar la mayoría de los errores de análisis de JSON:
- Use
JSON.stringify()para producir JSON, no la concatenación de cadenas. Esto se aplica a todos los lenguajes: utilice el serializador integrado. - Configure su editor para validar JSON al guardar. VS Code, IntelliJ y Sublime Text tienen validación de JSON integrada o disponible como complementos.
- Añada un paso de linting a su pipeline de CI. Una simple comprobación con
python -m json.tool < config.jsondetectará archivos mal formados antes de que lleguen a producción. - Cuando edite JSON a mano, use una herramienta con validación en tiempo real. El JSON Formatter valida a medida que escribe y muestra los errores de inmediato.
Para saber más sobre cómo escribir JSON limpio, consulte nuestros consejos de formato de JSON y la guía de sintaxis de JSON. Si se topa con errores de análisis al depurar respuestas de API con curl, nuestra guía para imprimir de forma legible la salida JSON de curl muestra cómo detectar respuestas mal formadas en la terminal antes de que lleguen a su código.
Cuándo JSON no es el formato adecuado
Si se encuentra peleando con las limitaciones de JSON con regularidad —queriendo comentarios, necesitando cadenas multilínea o lidiando con configuraciones anidadas complejas—, quizá valga la pena considerar YAML como alternativa. YAML admite comentarios, gestiona el texto multilínea con naturalidad y suele ser más legible para los archivos de configuración.
El inconveniente es que YAML es sensible a la indentación y tiene su propio conjunto de trampas (la coerción implícita de tipos, por ejemplo). Pero para archivos de configuración donde las personas necesitan leer y editar el contenido, YAML suele ser la opción más práctica. Siempre puede convertir entre ambos formatos cuando lo necesite: consulte nuestra guía sobre las diferencias entre YAML y JSON para una comparación más profunda.
Para terminar
Los errores de análisis de JSON son molestos, pero predecibles. Las mismas cinco o seis causas explican la gran mayoría de los casos:
- Comas finales
- Comillas simples
- Claves sin comillas
- Comentarios
- Caracteres BOM
- Corchetes descompensados
Familiarícese con estos patrones y corregirá la mayoría de los errores de análisis en segundos. Y cuando el archivo sea demasiado grande o demasiado complejo para depurarlo a simple vista, péguelo en el JSON Formatter y deje que haga el trabajo. Si quiere formatear JSON automáticamente directamente en la pestaña del navegador, eche un vistazo a nuestra comparación de extensiones de Chrome para formatear JSON.