JSON allows exactly six value types — object, array, string, number, boolean and null — and it allows them under a small set of rules that leave no room for interpretation. Almost every parse failure in real work is one of seven mistakes: a key without double quotes, a trailing comma, a comment, an unescaped control character, a malformed number, an invisible character copied from a document, or a file that was never JSON in the first place.
Knowing which of the seven you are looking at is faster than reading the document end to end, because each one leaves a distinctive error message and appears in a predictable place.
The seven failures
| # | What you wrote | What JSON requires | Error signature |
|---|---|---|---|
| 1 | {name: "Ada"} | {"name": "Ada"} | Expected property name in double quotes |
| 2 | {"a": 1,} | {"a": 1} | Unexpected token } or Expected double-quoted property name |
| 3 | {"a": 1} // total | no comments, ever | Unexpected token / |
| 4 | {"a": "two↵lines"} (literal line break) | {"a": "two\nlines"} | Bad control character in string |
| 5 | {"a": 01} or {"a": .5} | 0.1, 0.5, no leading + | Unexpected number |
| 6 | {"a": 1} with a non-breaking space | an ordinary space (U+0020) | Unexpected token at an innocent-looking spot |
| 7 | {a: 1} in a .js file, or {'a': 1} from Python | strict JSON | varies — often the first character |
Reading the error message properly
Modern JavaScript engines report three coordinates: a character offset, a line and a column. They are not the same thing, and the differences matter when you try to find the spot.
- Character offset is zero-based. A position of 0 means the first character of the file, so an error "at position 24" is at the 25th character.
- Line and column are one-based. Line 1 is the first line and column 1 is the first character of that line.
- The offset usually points at the character that broke the parse — frequently the character after the real mistake. A missing comma is reported at the token that should have followed it, so look at the line above as well as the reported line.
Older environments report only an offset, some report only a message, and a minified payload reports coordinates that refer to a line that no longer exists in the source you are holding. In that last case, pretty-print the payload before reading the number: the coordinates become useful once the text stops being one long line. The JSON formatter here reports line, column and a quoted copy of the offending line, which is usually enough to identify the fault without searching.
A checklist to work through in order
- Are all keys double-quoted? Single quotes, unquoted identifiers and template literals are all invalid. This is the most common failure after a hand-typed object literal.
- Is there a trailing comma? Allowed in JavaScript arrays and objects, forbidden in JSON. Check the line before every closing brace and bracket.
- Are the brackets balanced? A document truncated by a network read fails at the last character. Count
{against}, and[against], if the error points at the end of the file. - Are strings escaped correctly? A raw newline, tab or backspace inside a string is illegal; so is a lone backslash. Use
\n,\t,\\. - Are numbers legal? No leading zeros, no leading plus, no hexadecimal, no
NaN, noInfinity, no trailing dot. - Are there invisible characters? A byte-order mark at the start, a non-breaking space from a web page, or smart quotes pasted from a word processor will each produce an error that looks impossible. Search for characters outside the ASCII range in structural positions.
- Is this actually JSON? JSONP wrappers (
callback({...})), JavaScript object literals, YAML and newline-delimited JSON are all near misses. Strip the wrapper or convert the format before validating.
The escape sequences that exist
| Escape | Produces | Note |
|---|---|---|
\" | " | Required inside strings |
\\ | \ | A single backslash must be doubled |
\/ | / | Optional; useful inside <script> |
\n \t \r | newline, tab, carriage return | Raw versions are illegal in strings |
\b \f | backspace, form feed | Rarely needed in data |
\u00e9 | é | Also surrogate pairs for emoji |
There is no \' escape. A single quote inside a double-quoted string needs no escape at all, and a JSON string cannot be delimited by single quotes.
Why comments are rejected
JSON was specified as a data interchange format, not as a configuration language, so it has no comment syntax and no trailing-comma allowance. Extensions exist — JSON5 and JSONC add comments, trailing commas, single quotes and unquoted keys; JSON5 also adds hexadecimal numbers and NaN. Editors that use JSONC for settings, such as VS Code, will happily parse a commented file, which is why a configuration file can look valid in the editor and fail when a strict parser reads it.
If you need comments in a config file, choose a format that supports them (TOML, YAML, JSONC with a loader that expects it) rather than adding comments to JSON and hoping. If you must ship commented JSON to a strict consumer, strip the comments at build time, not by hand.
Valid JSON that still breaks things
Passing the parse is not the same as being correct. Four problems survive validation:
- Duplicate keys.
{"a": 1, "a": 2}is syntactically legal and almost every parser silently keeps the last value. Two systems reading the same document can disagree about its content, and the disagreement is invisible. - Integers beyond 253. Numbers are parsed as IEEE 754 doubles in JavaScript-based consumers, so a 19-digit database ID loses its last digits and stops matching. Send large IDs as strings.
- Dates as strings with no format.
"03/04/2026"is March 4th to one reader and April 3rd to another. ISO 8601 with an offset (2026-03-04T10:00:00Z) removes the ambiguity. - Deep nesting. Parsers have recursion limits; a 10,000-level nested object can throw a stack error rather than a syntax error, which reads like a bug in the parser and is really a data-model problem.
There is also a serialisation asymmetry worth knowing: JSON.stringify turns undefined, functions and symbols inside objects into nothing (the key disappears) and turns NaN and Infinity into null. Data can therefore change shape on the way out of a program without any error being raised.
FAQ
Does JSON allow a trailing comma after the last item?
No. Trailing commas are invalid in arrays and objects alike, and strict parsers reject them. They are permitted in JavaScript source and in JSON5/JSONC, which is the source of most of the confusion — the file looks fine in the editor that produced it and fails in the API that consumes it.
Can a JSON document start with an array instead of an object?
Yes. RFC 8259 defines a JSON text as any serialised value, so a top-level array, string or number is valid. Some older specifications and some libraries assumed an object at the root; if a consumer rejects your array, that is a limitation of the consumer, not of JSON. Wrapping the array in an object with a named key is the portable fix.
Why does my JSON fail only in production?
The usual causes are a byte-order mark added by an editor or a build step, a proxy that rewrites the payload, an HTML error page returned instead of JSON (the first character is <), or a different parser version with stricter rules. Log the first hundred characters of the raw response before parsing — the first character alone identifies the HTML-page case.
Format and validate a payload in the TextBench JSON formatter, then read why encoding is not encryption if the data travels inside a URL or a token.
Written by the TextBench team. Last updated November 19, 2026.