JSON es estricto de una forma que parece quisquillosa hasta que se conocen las reglas. Sin comas finales. Solo comillas dobles. Sin comentarios. Las claves deben ir entre comillas. Rompa una sola de ellas, en cualquier parte, y el documento entero se rechaza con un mensaje que señala una posición de carácter y rara vez dice qué está mal.
Esta página relaciona los mensajes de error con sus causas, y las causas con sus soluciones.
La respuesta rápida
- Encuentre la posición. Todo analizador (parser) informa de una línea y una columna, o de un desplazamiento en caracteres. Vaya allí; el error está en ese punto o justo antes.
- Busque los cinco habituales: una coma final, comillas simples, una clave sin comillas, un comentario, o una coma que falta entre dos elementos.
- Si el error está en la posición 0 o en la línea 1, columna 1, el problema no es el JSON. Recibió otra cosa: una página de error HTML, una respuesta vacía o una marca de orden de bytes (BOM).
Para obtener una ubicación precisa en cualquier equipo:
python3 -m json.tool broken.json
jq . broken.json
Cómo leer el mensaje de error
El mismo error se lee distinto en cada lenguaje. Encuentre el suyo y luego la causa:
| Mensaje (abreviado) | Dónde lo verá | Causa habitual |
|---|---|---|
Unexpected token '<', "<!DOCTYPE"... is not valid JSON | JavaScript | Recibió una página HTML, no JSON. Vea más abajo |
Unexpected end of JSON input | JavaScript | Respuesta vacía, o el archivo quedó cortado |
Expected double-quoted property name | JavaScript | Coma final antes de }, o una clave sin comillas o con comillas simples |
Unexpected non-whitespace character after JSON | JavaScript | Dos documentos seguidos, o basura después de la llave de cierre |
Bad control character in string literal | JavaScript | Un tabulador o salto de línea literal dentro de una cadena |
Expecting value: line 1 column 1 (char 0) | Python | Entrada vacía, o que no es JSON en absoluto |
Expecting property name enclosed in double quotes | Python | Coma final, comillas simples o clave sin comillas |
Expecting ',' delimiter | Python | Falta una coma entre dos elementos o miembros |
Extra data | Python | Más de un documento en el archivo (a menudo NDJSON) |
Invalid control character | Python | Un tabulador o salto de línea literal dentro de una cadena |
Unexpected UTF-8 BOM | Python | Marca de orden de bytes invisible al inicio del archivo |
Las causas, una por una
Coma final
{ "name": "Ada", "role": "admin", }
Permitida en código JavaScript, prohibida en JSON. El analizador llega a } cuando espera otra clave. Borre la última coma. Los archivos de configuración editados a mano y el código que construye JSON concatenando cadenas son las fuentes habituales.
Comillas simples
{ 'name': 'Ada' }
Las cadenas JSON siempre usan comillas dobles. Suele venir de un dict de Python mostrado con print() en lugar de json.dumps(). La solución real está en el código que lo produjo: serialice con una biblioteca JSON, no con formato de cadenas.
Claves sin comillas
{ name: "Ada" }
JavaScript válido, JSON inválido. Ponga comillas a todas las claves.
Comentarios
{ "port": 8080 // default }
JSON no tiene comentarios. Pero tenga cuidado antes de «arreglarlo»: algunos archivos están pensados para tenerlos. tsconfig.json, el settings.json de VS Code y muchos otros archivos de configuración son JSONC (JSON con comentarios) o JSON5, y las herramientas que los leen aceptan comentarios. Si el archivo es uno de esos, el problema es el analizador estricto al que se lo está dando, no el archivo.
Una coma que falta
{ "a": 1 "b": 2 }
El analizador lo reporta en "b", que está después del error. Cuando un error apunta a una clave perfectamente buena, mire el final de la línea anterior.
Valores que JSON no tiene
NaN, Infinity, undefined y los números con ceros a la izquierda como 007 son inválidos. También lo es un número hexadecimal, 0xFF. Use null, una cadena o un decimal simple, según lo que espere el lector.
Saltos de línea y tabuladores literales dentro de una cadena
Una cadena debe escribir los saltos de línea como \n y los tabuladores como \t. Un salto de línea real entre comillas es inválido. Suele ocurrir cuando se pega a mano un valor de varias líneas en un archivo JSON.
Barras invertidas
Una ruta de Windows como "C:\new\folder" falla, porque \n y \f son secuencias de escape. Duplique cada barra invertida, "C:\\new\\folder", o use barras normales.
Comillas tipográficas
“name” parece una cadena, pero no lo es: son comillas tipográficas, no ". Vienen de copiar JSON desde un documento, una app de chat o una diapositiva, o de escribir en un iPhone o iPad, donde la puntuación inteligente sustituye las comillas rectas mientras escribe. Desactívela en Ajustes → General → Teclado antes de editar JSON en iOS.
Errores en la «posición 0»: no es JSON
Cuando el error está en el primer carácter, lo que está mal es el contenido, no la sintaxis.
<en la posición 0 significa que analizó HTML. El servidor devolvió una página de error, una de inicio de sesión o un 404, y su código intentó leerla como JSON. Registre la respuesta sin procesar y el código de estado antes de analizar.- Una entrada vacía significa que la respuesta no tenía cuerpo, a menudo un
204 No Contento una solicitud que falló antes de que el servidor respondiera. - Un carácter invisible al inicio suele ser una marca de orden de bytes UTF-8 añadida por un editor de Windows. En Python, abra el archivo con
encoding="utf-8-sig"; en otros casos, vuelva a guardarlo como UTF-8 sin BOM.
NDJSON no es JSON roto
Un archivo con un objeto JSON por línea (.jsonl, .ndjson o salida de registros) falla con «Extra data» o «Unexpected non-whitespace» al inicio de la línea dos. Cada línea es válida por sí sola. Analícelo línea por línea, o deje que lo haga una herramienta que entienda el formato: jq -c . file.jsonl lee cada línea.
Reparar automáticamente
Para los descuidos comunes (comas finales, comillas simples, claves sin comillas, comentarios), la reparación automática es segura porque solo hay un significado razonable. Herramientas que lo hacen:
jsonrepair, una biblioteca de JavaScript y herramienta de línea de comandos.- La mayoría de los editores de código, mediante una extensión de JSON5 o «fix JSON».
- Una app editora de JSON que valida mientras escribe.
La reparación automática no es segura con un archivo truncado. Una herramienta de reparación cerrará los corchetes abiertos y le entregará un documento válido al que le faltan datos. Vuelva a descargarlo o a exportarlo.
En iPhone y iPad, Smart Json muestra el error en lenguaje claro, con su línea y columna. Go lleva el cursor hasta allí, y Fix repara comentarios, comas finales, comillas simples y claves sin comillas con un solo toque.
Nombra un error de JSON en palabras claras con su línea y columna, salta hasta él y repara comentarios, comas finales, comillas simples y claves sin comillas con un solo toque.
Qué haceCómo evitar que se rompa
Casi todos los archivos JSON inválidos se escribieron a mano o se armaron concatenando cadenas. Genere JSON con un serializador (json.dumps, JSON.stringify, JSONEncoder) y valide los archivos editados a mano antes de confirmarlos. Un hook de pre-commit que ejecute jq . file.json > /dev/null detecta todo lo anterior antes de que lo vea otra persona.