How to find and fix JSON syntax errors

What a JSON document may contain

JSON is a small format. A value is an object, an array, a string, a number, true, false or null. Objects hold string keys in double quotes. Strings use double quotes and a short list of backslash escapes. That is all RFC 8259 allows, which is why many files that look like JSON to a person fail in a parser.

Most real errors come from a file written by hand, copied from JavaScript source, or edited by a tool that does not enforce the rules. The sections below go through the causes in rough order of how often they occur.

The eight usual causes

• **Trailing comma.** {"a": 1,} and [1, 2,] are invalid. JSON has no trailing commas, though many config formats do. The parser usually reports the closing brace or bracket as the unexpected token.
• **Single quotes.** {'a': 1} is JavaScript, not JSON. Keys and strings must use double quotes.
• **Unquoted keys.** {a: 1} is a JavaScript object literal. In JSON every key is a quoted string.
• **Comments.** Neither // nor /* */ is allowed. If a file needs comments, it is probably JSONC or JSON5 and needs a parser for that format, or the comments need to be removed first.
• **Missing comma between items.** Two values side by side, such as "a": 1 "b": 2, make the parser stop at the second key.
• **Bad number forms.** Leading zeros (012), a leading plus (+1), a bare decimal point (.5) and NaN and Infinity are all invalid, as is the JavaScript word for a missing value. JSON numbers are decimal digits with an optional fraction and exponent.
• **Unescaped control characters.** A raw newline or tab inside a string is invalid; write \n or \t instead. This often appears when text is pasted into a string.
• **Extra text after the value.** A second document after the first, or a stray character at the end, is reported as an error at that position. Log files with one JSON object per line are not one JSON document; parse each line separately.

Reading the line and column

Paste the document into the formatter above. It reports the line and column where parsing stopped. The mistake is usually at that position or just before it: for a missing comma, the error points at the start of the next key; for a trailing comma, at the closing bracket after it; for a missing closing quote, often at the end of the file, because the string never ended.

When the position is at the very end, look for an unclosed string, brace or bracket earlier in the file. Formatting the part of the document you trust, then adding the rest back in halves, finds the break in a few steps.

Problems that parse but are still wrong

• **Duplicate keys.** RFC 8259 says names within an object should be unique and that behavior is unpredictable otherwise. JavaScript keeps the last value, other parsers may keep the first or reject the document.
• **Large integers.** JavaScript stores numbers as 64-bit floating point values, so integers above 9,007,199,254,740,991 (2^53 minus 1) can lose precision after parsing. IDs from other systems should travel as strings.
• **Encoding.** RFC 8259 requires JSON exchanged between systems to be UTF-8. A file with a byte order mark or another encoding may fail in strict parsers even when the text looks fine.
• **Key order.** Objects are unordered in the specification. Sorting keys before comparing or committing a file makes diffs readable, and the formatter has a sort option for that.

After it parses: compare, convert, validate

Once the syntax is fixed, the JSON diff lists added, removed and changed values by path, which is more useful than a text diff when two files differ only in formatting. To move between formats, use the YAML to JSON converter or JSON to CSV. All of them run in your browser, so configuration with secrets in it never leaves the tab.

Minify only for transport. For files people read and review, keep two-space indentation and sorted keys so changes stay small in version control.

A short checklist

• Run the document through a validator before debugging the code that reads it.
• Look at the reported line, then one line above it.
• Search for single quotes, trailing commas and comments first; they account for most failures.
• Treat IDs and money as strings or integers in smallest units, never as floating point.
• Keep generated JSON generated: write it with a serializer, not string concatenation.

Related

• 01JSON Formatter and Validator
• 02JSON Diff
• 03YAML to JSON Converter
• 04JSON to CSV Converter