Learn / JSON / Common Gotchas
Lesson 6 of 6

Common Gotchas

JSON's syntax is small, but that smallness is exactly why the mistakes people make with it are so consistent and predictable. Here's the field guide to the ones that trip up almost everyone at least once.

💡 The Bottom Line

Nearly every "invalid JSON" error traces back to one of a handful of habits carried over from a more forgiving language or format — trailing commas, single quotes, or comments. None of those are JSON syntax errors by accident; JSON deliberately left them out to stay simple and unambiguous for every parser.

Gotcha 1: trailing commas

{
  "a": 1,
  "b": 2,
}

That trailing comma after "b": 2 is invalid. JavaScript object literals allow it; JSON does not. This is probably the single most common JSON syntax error, precisely because it's harmless (and even stylistically encouraged by some linters) in the source languages people are used to writing.

Gotcha 2: single quotes

{ 'name': 'Ada' }   // invalid — must be double quotes
{ "name": "Ada" }   // valid

JSON strings — both keys and values — must use double quotes. There is no exception for this, even though single quotes work fine in JavaScript, Python, and most other languages' string literals.

⚠️ Gotcha 3: no comments allowed

JSON has no comment syntax at all — not //, not /* */, nothing. This trips up developers constantly, especially when writing JSON configuration files by hand, where you'd naturally want to explain a setting. Some tools support a relaxed superset called JSON5 or JSONC (JSON with Comments) — VS Code's own settings files use JSONC — but plain JSON parsers will reject a comment as a syntax error.

Gotcha 4: numbers that look fine but aren't

{ "value": 01 }    // invalid — leading zero
{ "value": .5 }    // invalid — no leading digit before the decimal
{ "value": 5. }    // invalid — no trailing decimal point
{ "value": NaN }   // invalid — NaN is not a JSON value
{ "value": 0.5 }   // valid

JSON's number format is stricter than most programming languages' number literals. A leading zero, a missing digit before or after the decimal point, or special values like NaN/Infinity (which JavaScript itself supports as numbers, but JSON does not) will all fail.

🙋 There Are No Dumb Questions

Q: My JSON.parse error message just says "Unexpected token" — how do I actually find the problem?
A: Most modern JS engines now include a position/line number in that error message — read it carefully, it usually points close to the exact character. If not, paste the JSON into an online JSON validator/linter, which will typically highlight the exact line and explain what it expected instead. Trailing commas and single quotes (Gotchas 1 and 2) account for the vast majority of these errors, so check for those first.

🔧 Try It Yourself

Take this broken JSON and find all three mistakes before running it through a parser to check yourself: {'name': "Ada", "age": 36,}. (Hint: there's a quote-style issue, and a comma issue.)

✅ Quick Check

Which of these is a valid reason a JSON document fails to parse?

That's the whole track — time for the recap.

← Back to
Next →