Resolviendo "Unexpected token in JSON" y errores comunes de análisis de JSON: Una Guía Completa

JSON (JavaScript Object Notation) es la columna vertebral de la comunicación web moderna. Ya sea que esté creando una API REST, configurando un servidor o almacenando el estado de una aplicación, JSON está en todas partes. Sin embargo, su estricta sintaxis a menudo conduce a errores frustrantes como SyntaxError: Unexpected token, JSON.parse: unexpected character o simplemente invalid JSON format.

In esta guía, analizaremos los errores de análisis de JSON más comunes, explicaremos por qué ocurren y le mostraremos exactamente cómo solucionarlos.

1. Mensajes de error de JSON comunes

Cuando un analizador (como JSON.parse() en JavaScript) encuentra un JSON no válido, lanza un error. Dependiendo del entorno, es posible que vea:

• Navegador (Chrome/V8): SyntaxError: Unexpected token ' in JSON at position 0
• Firefox: SyntaxError: JSON.parse: unexpected character at line 1 column 1 of the JSON data
• Node.js: SyntaxError: Unexpected token ... in JSON at position ...
• Python: json.decoder.JSONDecodeError: Expecting property name enclosed in double quotes

La información clave suele ser el carácter que no esperaba y la posición (o línea/columna) donde ocurrió.

---

2. Principales causas y soluciones

2.1 Comillas simples en lugar de dobles

JSON requiere estrictamente comillas dobles (") tanto para las claves como para los valores de cadena. Las comillas simples (') son válidas en los objetos de JavaScript pero no válidas en las cadenas de JSON.

El error (single quotes in JSON):

{
  'name': 'Tool3M'
}

La solución: Reemplace todas las comillas simples por comillas dobles.

{
  "name": "Tool3M"
}

2.2 Comas finales (Trailing Commas)

A diferencia del JavaScript moderno, JSON no permite una coma después del último elemento en un objeto o matriz.

El error (trailing comma in JSON):

{
  "id": 1,
  "status": "active",
}

La solución: Elimine la coma después de la última propiedad.

{
  "id": 1,
  "status": "active"
}

2.3 Claves sin comillas

En JSON, las claves siempre deben ser cadenas encerradas entre comillas dobles.

El error:

{
  id: 123
}

La solución: Encierre las claves entre comillas dobles.

{
  "id": 123
}

2.4 Comentarios en JSON

El estándar JSON no admite comentarios (// o /* */) (comments in JSON). Si bien algunas herramientas (como VS Code para tsconfig.json) los permiten, el JSON.parse() estándar fallará.

El error:

{
  "id": 1 // Este es un comentario
}

La solución: Elimine todos los comentarios antes de analizar. Si debe tener metadatos, use una propiedad como "__comment": "texto".

2.5 Valores especiales: NaN, Infinity y Undefined

JSON no admite NaN, Infinity, -Infinity o undefined. Estos son valores específicos de JavaScript.

El error (NaN in JSON, Infinity in JSON):

{
  "value": NaN,
  "expired": undefined
}

La solución: Use null o un marcador de posición de cadena/número en su lugar.

{
  "value": null,
  "expired": null
}

2.6 Caracteres de control y saltos de línea

Las cadenas en JSON no pueden contener caracteres de control sin procesar (como pestañas o saltos de línea reales) a menos que estén escapados.

El error:

{
  "description": "Esta es una 
cadena de varias líneas"
}

La solución: Use \n para saltos de línea y \t para pestañas.

{
  "description": "Esta es una \ncadena de varias líneas"
}

---

3. Solución de problemas avanzada

3.1 BOM (Byte Order Mark)

A veces, un archivo parece perfecto pero aún arroja un SyntaxError en la posición 0. Esto suele deberse a un carácter UTF-8 BOM oculto al principio del archivo. Solución: Vuelva a guardar el archivo como "UTF-8 sin BOM".

3.2 Caracteres escapados incorrectamente

Si su cadena contiene una barra invertida (\) o una comilla doble ("), deben escaparse.

• Correcto: "path": "C:\\Windows\\System32"
• Correcto: "quote": "Él dijo \"Hola\""

---

4. Medidas de prevención

1. Use un Linter: Use herramientas como ESLint con el jsonc-parser o la validación JSON integrada de VS Code.
2. Formateo automático: Siempre pase su JSON por un formateador antes de guardarlo en un archivo de configuración.
3. Validación de esquema: Use JSON Schema para definir la estructura de sus datos y validarlos mediante programación.
4. Try-Catch: Al analizar datos dinámicos, siempre envuelva JSON.parse() en un bloque try...catch para manejar los errores con elegancia.

try {
  const data = JSON.parse(userInput);
} catch (e) {
  console.error("Error al analizar JSON:", e.message);
  // Mostrar un error amigable al usuario
}

---

5. FAQ: Preguntas frecuentes

Q: ¿Por qué recibo "Unexpected token < in JSON at position 0"?

A: Esto casi siempre significa que su código esperaba JSON pero recibió HTML. Esto sucede típicamente cuando una llamada a la API falla y el servidor devuelve una página de error HTML (como una página 404 o 500) en lugar de la respuesta JSON esperada.

Q: ¿Puedo usar números hexadecimales en JSON?

A: No. JSON solo admite números decimales estándar. 0xFF causará un error de análisis (JSON parse error). Use 255 en su lugar.

Q: ¿Cómo manejo archivos JSON grandes que bloquean mi analizador?

A: Para archivos muy grandes, use un analizador de "transmisión" (streaming) como JSONStream (Node.js) o ijson (Python), que procesa el archivo pieza por pieza en lugar de cargarlo todo en la memoria.

---

6. Herramienta de comprobación rápida

Si tiene dificultades para encontrar esa coma que falta o esa comilla mal colocada, use nuestro Formateador y Validador de JSON. Te permitirá:

• Resaltar instantáneamente errores de sintaxis.
• Corregir problemas comunes como comillas simples o comas finales.
• Formatear su JSON para que sea legible por humanos.

---

Errores relacionados

• Resolviendo errores de 'invalid base64 string'
• Cómo corregir 'malformed URL' en JavaScript
• Comprendiendo los errores de sangría de YAML