debugging 6 min read May 2026

How to Debug JSON Errors: Common Mistakes and How to Fix Them

JSON is a deceptively strict format. One misplaced comma, one unescaped backslash, or one single quote instead of a double quote, and the entire document fails to parse. Unlike HTML — which browsers parse leniently — JSON parsers in every language are unforgiving. A syntax error anywhere in the file means nothing parses successfully.

How JSON parsers report errors

When a JSON parser encounters invalid syntax, it throws an error with a position indicator. Learning to read these messages is the first step to fixing them quickly.

In JavaScript:

JSON.parse('{"name": "Alice",}')
// SyntaxError: Unexpected token } in JSON at position 18

In Python:

import json
json.loads('{"name": "Alice",}')
# json.decoder.JSONDecodeError: Expecting property name enclosed
# in double quotes: line 1 column 18 (char 17)

Both errors point to approximately position 18 — the closing brace that follows the trailing comma. The key insight: the reported position is where the parser gave up, not necessarily where the mistake is. The actual error (the trailing comma) is one character earlier.

The most common JSON errors

1. Trailing commas

The single most common JSON mistake. JSON does not allow a comma after the last item in an object or array.

// Invalid JSON
{
  "name": "Alice",
  "age": 30,       ← trailing comma
}

// Valid JSON
{
  "name": "Alice",
  "age": 30
}

This trips up developers coming from JavaScript, which allows trailing commas in object and array literals. Many JSON-adjacent formats (JSON5, JSONC) also allow them, which adds to the confusion.

2. Single quotes instead of double quotes

JSON strictly requires double quotes for both keys and string values. Single quotes are not valid.

// Invalid JSON
{'name': 'Alice'}

// Valid JSON
{"name": "Alice"}

3. Unquoted keys

In JavaScript objects, keys can be unquoted. In JSON, every key must be a double-quoted string.

// Invalid JSON — JavaScript object syntax, not JSON
{name: "Alice"}

// Valid JSON
{"name": "Alice"}

4. Comments

JSON has no comment syntax. No //, no /* */, no #. Any character that isn't part of the value structure will cause a parse error.

// Invalid JSON — comments are not allowed
{
  "port": 8080, // HTTP port
  "host": "localhost"
}

// Valid JSON
{
  "port": 8080,
  "host": "localhost"
}

If you need a config file format with comments, consider YAML, TOML, or JSON5. Many editors support these formats while still outputting valid JSON for consumption.

5. Undefined, NaN, and Infinity

JSON supports exactly six value types: strings, numbers, booleans (true/false), null, objects, and arrays. JavaScript-specific values like undefined, NaN, and Infinity are not valid JSON.

// Invalid JSON
{
  "score": NaN,
  "limit": Infinity,
  "result": undefined
}

// Valid alternatives
{
  "score": null,
  "limit": null,
  "result": null
}

6. Unescaped special characters in strings

Certain characters must be escaped within JSON strings. The characters that require escaping are: " (double quote), \ (backslash), and control characters including newlines (\n), tabs (\t), and carriage returns (\r).

// Invalid JSON — unescaped backslash in Windows path
{"path": "C:\Users\alice\documents"}

// Valid JSON — backslashes escaped
{"path": "C:\\Users\\alice\\documents"}

// Invalid JSON — literal newline in string
{"message": "line one
line two"}

// Valid JSON — escaped newline
{"message": "line one\nline two"}

7. Numbers formatted incorrectly

JSON numbers cannot have leading zeros (except for 0 itself), cannot start with a decimal point, and cannot end with a decimal point. Hexadecimal notation is not supported.

// Invalid JSON numbers
{"a": 07, "b": .5, "c": 5., "d": 0xFF}

// Valid JSON numbers
{"a": 7, "b": 0.5, "c": 5.0, "d": 255}

Debugging strategies

Use a formatter with error highlighting

The fastest way to find a JSON error is to paste the JSON into a formatter that highlights the exact error position. A good formatter will point to the line and character where parsing failed and describe what it expected to find instead.

Use the binary search technique for large documents

For very large JSON documents where the error isn't obvious, the binary search approach works well: remove the second half of the document (make sure you leave valid JSON structure) and try to parse. If it succeeds, the error is in the removed half. If it fails, the error is in the first half. Repeat until you've narrowed it down to the problem area.

Check the character before the error position

JSON parsers report the position where they couldn't continue — usually one character after the actual mistake. If the error is at position 47, look carefully at positions 45–47.

Watch for invisible characters

Zero-width spaces, non-breaking spaces, and other Unicode whitespace characters can sneak into JSON when copying from a web page or document editor. They're invisible in most editors but cause parse failures. A hex editor or a formatter that highlights non-ASCII characters can identify these.

Watch for BOM: Some text editors prepend a UTF-8 BOM (byte order mark: EF BB BF) to files. JSON parsers in some languages reject files with a BOM. If a file looks valid but fails to parse, check for a BOM at the start of the file.

Preventing JSON errors in production

The best way to handle JSON errors is to prevent them from reaching production:

Always use a serialization library to generate JSON — never build JSON strings by hand with string concatenation. JSON.stringify(), Python's json.dumps(), and equivalent functions in every language correctly handle escaping and structure.
Validate API responses before processing. Wrap JSON.parse() in a try/catch and handle parse failures gracefully rather than crashing.
Use schema validation (JSON Schema, Zod, Joi) to validate not just syntax but structure — required fields, correct types, valid value ranges.
Lint configuration files in CI. If your project uses JSON config files, run a JSON validator in your CI pipeline before merging changes.

Quick check: In any browser console, run JSON.parse(yourString). If it throws, the error message includes the position. If it returns an object, your JSON is valid.

// summary

Parser errors report where parsing failed, not where the mistake is — look one character earlier
Most common errors: trailing commas, single quotes, unquoted keys, comments, and unescaped backslashes
JSON supports only: strings, numbers, booleans, null, objects, and arrays — no undefined, NaN, or Infinity
Always generate JSON with a library, never build it by string concatenation
Wrap JSON.parse() in try/catch and validate the structure after parsing
For large documents, use binary search to isolate the error position