Locating a JSON error when the message only gives you a position
JSON parsers report a character offset, which usually lands just after the actual mistake. How to map that offset to a line and column, plus the four causes behind most failures: trailing commas, single quotes, comments and a BOM.
Why the reported position is always slightly off
Parsers read character by character and complain only when they meet something unexpected. A stray comma is not itself rejected — the parser expects a key next and only realises something is wrong when it meets a closing brace instead. So the offset usually points at the character after the mistake. Practically: on "Unexpected token }", look one position back for a trailing comma; on an unexpected quote character, check the quote style; on "Unexpected end of JSON input", look for an unclosed bracket.
Turning the offset into a line and column
The offset counts characters from the start of the input, newlines included. To get a line number you count newlines up to that point, which is exactly what a formatter does while it scans — and it can highlight the offending line. One trap when scripting it yourself: most runtimes report UTF-16 code units, so a CJK character counts as one unit even though it displays as two columns. Slice by code units, not by visible characters.
Four causes account for most failures
In rough order of frequency:
- Trailing commas: {"a":1,} is valid JavaScript and invalid JSON. Common in hand-written configs and hand-edited API responses.
- Single quotes: JSON accepts only double quotes. Guaranteed to appear when pasting from a JS object or a Python dict.
- Comments: the spec has none. // and /* */ are illegal characters. If you need comments, use JSON5 or JSONC — do not force them into JSON.
- A BOM: Windows Notepad prepends three bytes (EF BB BF) when saving UTF-8, the parser treats them as the first character, and the error lands at position 1. This is the most confusing one.
Three rarer ones that still bite
NaN and Infinity: the spec has number literals only; NaN, Infinity and undefined are not valid values. JSON.stringify turns them into null, but a hand-written file containing them fails immediately. Number formats: leading zeros (01), a leading plus (+1) and a trailing decimal point (1.) are all illegal. Data assembled from Excel or CSV often brings these along. Invisible characters: JSON copied from a web page occasionally carries zero-width spaces (U+200B) or non-breaking spaces (U+00A0) that look like nothing and make the parser fail at a position that appears perfectly fine. When "there is obviously nothing wrong", paste it into an editor that can reveal invisible characters.
Do not eyeball large files
Above a few tens of KB, visual inspection stops working. A workable routine: format the whole document so the structure unfolds; if formatting itself fails, look for the nearest unbalanced bracket after the reported offset; if that fails, bisect — delete the second half and see whether the error persists, halving the suspect range each time. One warning: formatting a JSON file of hundreds of MB will freeze a browser tab. Use jq or a Node script for those instead of a web tool.
Common questions
- Why does JSON forbid comments
- Historical: JSON was extracted as a minimal subset of JavaScript object literal syntax, and comments plus trailing commas were deliberately left out. Comments give the same document two readings and blur the line between machine-generated and hand-maintained config. If you need them, use JSON5, JSONC or YAML, or agree on a "_comment" field.
- The error says position 1 but the first character looks fine
- Almost always a BOM. Open the file in a hex viewer: if it starts with EF BB BF, that is it. Re-save as UTF-8 without BOM, or strip those three bytes in a script.
- Formatting reordered my keys. Does it matter?
- Per the spec a JSON object is an unordered set of pairs, so order carries no meaning and relying on it is unsafe. In practice some systems do depend on insertion order, especially when a JS parser iterates the object directly, which is why formatters preserve original order and only touch indentation and line breaks.