Debugging Malformed JSON: A Field Guide

By Marcus Vane · September 4, 2026 · Developer Tools

Almost every JSON parse failure comes from the same short list of causes. Learn to recognise them from the error message and stop bisecting files by hand.

JSON is a deliberately small format, which is why the ways it can break are few and highly repetitive. Once you can map a parser error message to its usual cause, most debugging takes under a minute instead of the twenty most people spend deleting halves of the file.

The usual suspects

• A trailing comma after the last element of an array or object. Legal in JavaScript, illegal in JSON, and by far the most common cause.
• Single quotes instead of double quotes. JSON permits only double quotes, for both keys and string values.
• Unquoted keys, which look fine in a JavaScript object literal and are invalid here.
• Comments. JSON has none, and a configuration file with a helpful explanatory line will not parse.
• Unescaped characters inside strings, particularly a raw newline, tab or backslash in a Windows path.
• NaN, Infinity or undefined, none of which exist in JSON. Use null.
• A byte order mark at the start of a file saved by a Windows editor, invisible but fatal.

Reading the error message

Parsers report the position where parsing became impossible, which is often after the actual mistake. "Unexpected token }" usually means a trailing comma just before it. "Unexpected end of input" means an unclosed bracket or brace somewhere earlier, and the reported position is simply the end of the file. "Unexpected token <" almost always means you received an HTML error page instead of the JSON API response you expected, which is a networking problem rather than a formatting one.

A systematic process

1. Paste the document into a validator and read the reported line and column.
2. Look immediately before that position, not at it, since the parser fails after the real error.
3. Format the document, because indentation makes an unclosed brace visible instantly.
4. Check the very first character for a byte order mark or stray whitespace.
5. If the file came from an API, print the raw response to confirm it is JSON at all.
6. For very large files, validate a structural sample first to establish whether the problem is systematic or a one-off.

Avoiding the problem entirely

Generate JSON with a serialiser rather than string concatenation. Hand-built JSON breaks on the first value containing a quotation mark, and every language ships a correct encoder. For configuration files that humans must edit and annotate, a format that supports comments is a better fit than JSON with a comment-stripping preprocessor bolted on.

Wrapping up

Validate, format, look just before the reported position, and remember that the error message names the symptom rather than the cause.

Validate and pretty-print JSON with precise error positions.

Try the JSON Formatter tool.

SwiftMultiTool — free online tools for everyone. Home · Blog · About · FAQ · Contact