The JSON mistakes behind most parse errors, and how to fix them

Most JSON parse errors come from a short list of mistakes: a trailing comma, a single-quoted string, a comment, an unquoted key, a value such as NaN or undefined, or curly quotes copied from a document. JSON is stricter than the JavaScript it resembles, so code that looks fine to a person can be rejected by a parser. The error message points to a line and a column, and the fix is usually at or just before that spot.

Format JSONJSON won’t parse — free, runs in your browserOpen →

The rules JSON enforces

A JSON document is one value: an object in braces, an array in brackets, a string, a number, true, false or null. Inside those values:

• Every key and every string uses straight double quotes, such as "name".
• Commas separate items, and there must be no comma after the last item in an object or array.
• Numbers cannot have a leading plus sign, and NaN, Infinity and undefined are not valid numbers or values.
• Comments are not allowed at all.
• Keys must be strings, so an unquoted key such as name: is invalid.

Some parsers accept a few of these by default, and some tools accept JSON with comments as a convenience. That leniency hides the problem until the file reaches a stricter reader, so write the strict form.

Reading the error message

Parsers report the first place where they could not continue. The message names the problem and gives a position, usually a line and a column. Here is a small file with a trailing comma in an array and another after the last property:

{
  "name": "Ada",
  "tags": ["a", "b",],
}

Python reports this as "Illegal trailing comma before end of array: line 3 column 20". The wording differs between tools, and some older parsers say only "Unexpected token" with a character offset. Go to the position reported, then look at the character just before it. The real mistake is often a comma, quote or brace one or two characters earlier than the reported spot.

A few more messages, from Python's parser, and what they usually mean:

• "Expecting property name enclosed in double quotes" for '{'a': 1}' means a single-quoted or unquoted key.
• "Expecting value" at a position where you expected a number or string often means a smart quote, since the parser sees it as an unknown character.
• "Expecting ',' delimiter" usually means a missing comma between two items, or a comment in the middle of the data.

Smart quotes and copied text

Smart quotes are the most confusing case, because they look almost the same as straight quotes. A JSON file copied from a word processor, a web page or a chat message can contain curly double quotes. The file looks right to you and fails to parse, because the parser sees “x” as an unknown character instead of a string delimiter.

Hidden characters cause the same kind of failure. A non-breaking space between two values is not whitespace to the parser. Remove hidden characters before you try to repair the structure by hand, and then fix the quotes.

Single quotes, comments and unquoted keys

Many developers write JSON-like data in a language that allows more:

• Single quotes are valid in JavaScript and Python literals, but JSON requires double quotes. Replace {'a': 1} with {"a": 1}.
• Comments such as // or /* */ must be removed. If you need notes, put them in a separate field, or use a format designed for configuration files.
• Unquoted keys are common in JavaScript object literals. Add the quotes.
• NaN and undefined are not JSON. Use null for a missing value, or a string if the value is text.

Be careful with a blanket find-and-replace. Changing every single quote to a double quote breaks any string that contains an apostrophe, such as "Ada's notes".

Fix the structure step by step

1. Paste the file into the JSON formatter. Formatting it with consistent indentation makes the structure visible, and most formatters point at the first error.
2. Fix the first error only, then check again. One mistake can produce several errors further down.
3. Check that every opening brace or bracket has a closing one, and that the nesting is what you intend.
4. Validate the final file with the parser your application uses, not only with a web tool. Parsers differ slightly.

Edge cases

• Trailing commas in generated files. Some tools write them. If you produce JSON by hand-building strings, use the serialiser of your language, which writes valid output.
• Duplicate keys. JSON allows them, but most parsers keep only the last value. Duplicate keys are a bug waiting to happen.
• Big numbers. Very large integers can lose precision in some parsers, so store identifiers as strings if they are longer than the parser can represent exactly.

Quick answers

Why does my JSON fail when it looks correct?

The usual causes are a trailing comma, single quotes, a comment, or curly quotes copied from a document. Check the position in the error message and the character just before it.

Can JSON have comments?

No. The JSON standard does not allow comments. Remove them, or move the notes into a field of their own.

What should I use instead of undefined in JSON?

Use null when a value is missing on purpose, or omit the key entirely. undefined is a JavaScript value and has no JSON representation.