You’ve spent twenty minutes staring at a JSON file. Your API call keeps failing. The error message is some cryptic nonsense about “unexpected token.” And the JSON looks fine to you.
We’ve all been there.
JSON is a strict format. That strictness is what makes it reliable across every programming language on Earth – but it’s also what turns a missing comma into a debugging nightmare. The good news? Almost every broken JSON file fails for one of the same ten reasons. Once you know what to look for, you can spot the problem in seconds.
This guide covers all ten, with real examples of broken JSON and exactly how to fix each one. Bookmark it – you’ll come back.
Quick tip before we start: the fastest way to find any JSON error is to paste it into a JSON validator. A good one highlights the exact line and character where things go wrong, which saves a ton of squinting. But understanding why each error happens means you’ll write better JSON from now on – so let’s go through them.
1. Trailing Commas
This is the #1 mistake we see, and it’s almost always the culprit when JavaScript developers move from objects to JSON.
Broken:
{
"name": "Alice",
"age": 30,
}That comma after 30 is illegal in JSON. JavaScript allows it. Python dicts allow it. JSON does not.
Fix:
json
{
"name": "Alice",
"age": 30
}Why this trips people up: Modern languages forgive trailing commas because they make diffs cleaner. JSON predates that convention, and the spec hasn’t budged.
Pro tip: When you reorder properties in an object, the new last property gets a comma it shouldn’t have. Always check the bottom of your object after any edit.
2. Single Quotes Instead of Double Quotes
Broken:
{
'name': 'Alice'
}Fix:
json
{
"name": "Alice"
}JSON only accepts double quotes — for both keys and values. No exceptions.
Why this trips people up: Python’s default repr uses single quotes. Copy a dict from a Python console, paste it into a JSON file, and every quote is wrong. Same story with JavaScript object literals.
Pro tip: If you’re exporting JSON from Python, always use json.dumps(), never str(). Don’t hand-convert.
3. Unquoted Keys
Broken:
json
{
name: "Alice"
}Fix:
json
{
"name": "Alice"
}JSON requires every key to be a string wrapped in double quotes. JavaScript lets you skip the quotes on simple keys. JSON does not.
This is usually a dead giveaway that someone copy-pasted a JavaScript object and called it JSON. They’re related but they’re not the same thing.
4. Missing Commas Between Properties
Broken:
json
{
"name": "Alice"
"age": 30
}Fix:
json
{
"name": "Alice",
"age": 30
}Every property pair (except the last) needs a comma after it.
Why this one’s painful: the error message usually points to the next line, not the line missing the comma. So you’ll see “unexpected token at line 4” when the actual problem is on line 3. Always check the line above the one the error points to.
5. Comments
Broken:
json
{
// This is the user object
"name": "Alice"
}Fix:
json
{
"name": "Alice"
}JSON has no concept of comments. Not //, not /* */, not #. Nothing.
Workaround: If you really need to document a JSON config, add a comment key:
json
{
"_comment": "This is the user object",
"name": "Alice"
}Or use JSONC (JSON with Comments) — but only if you control the parser and you know it supports it. Most don’t.
6. Unescaped Special Characters
Broken:
json
{
"path": "C:\Users\Alice"
}The backslashes aren’t escaped, so the parser tries to interpret \U and \A as escape sequences. Same problem if you have a literal double quote inside a string value:
json
{
"quote": "She said "hi""
}Fix:
json
{
"path": "C:\\Users\\Alice",
"quote": "She said \"hi\""
}The escape sequences you’ll use most often in JSON: \\ (backslash), \” (double quote), \n (newline), \t (tab), and \uXXXX (unicode).
7. Mismatched or Missing Brackets
Broken:
json
{
"users": [
{"name": "Alice"},
{"name": "Bob"
]
}Bob’s object is missing its closing brace. Easy to miss in a big file.
Fix:
json
{
"users": [
{"name": "Alice"},
{"name": "Bob"}
]
}This is where a JSON beautifier earns its keep. Properly indented JSON makes mismatched brackets visible immediately – what you can’t see in minified one-liner JSON jumps out the moment it’s formatted.
8. Wrong Capitalization of true, false, and null
Broken:
json
{
"active": True,
"deleted": Null
}Fix:
json
{
"active": true,
"deleted": null
}JSON is case-sensitive. true, false, and null are all lowercase. Always.
Why this trips people up: Python uses True, False, None. C# uses True/False. Copy-paste from either, and you’ve got a problem.
9. Invalid Number Formats
JSON has strict rules about how numbers can be written, and several formats that look normal in code are actually invalid.
Broken:
json
{
"id": 007,
"rate": .5,
"balance": 100.,
"code": 0xFF
}Here’s what’s wrong with each one:
- 007 — leading zeros aren’t allowed (except for the number 0 itself, or decimals like 0.5)
- .5 — must be 0.5; the leading digit is required
- 100. — must be 100 or 100.0; numbers can’t end in a dot
- 0xFF — hex notation isn’t valid JSON
Fix:
json
{
"id": 7,
"rate": 0.5,
"balance": 100,
"code": 255
}If you actually need to preserve leading zeros (like a phone number, ZIP code, or product SKU), store it as a string: “id”: “007”.
10. Unexpected End of Input (Truncated JSON)
Broken:
json
{
"name": "Alice",
"items": ["apple", "banana",The string just… stops. No closing bracket, no closing brace. The parser hits the end of the file and says “wait, you weren’t done.”
This usually means one of three things:
- Your API response was cut off mid-transfer
- You copied JSON from a console or log that truncated long output
- A file write didn’t complete
Fix: Complete the structure.
json
{
"name": "Alice",
"items": ["apple", "banana"]
}Pro tip: If you keep getting truncated JSON from an API, check the response headers for Content-Length and verify it matches what you actually received. Often the API isn’t broken — your network or proxy layer is silently chopping the response.
Bonus: Three Sneaky Issues That Aren’t on the Top 10 List
These don’t show up on most “common JSON errors” articles, but they’ve burned plenty of developers.
Duplicate keys. Technically allowed by the JSON spec, but most parsers silently keep only the last value. So {“name”: “Alice”, “name”: “Bob”} becomes {“name”: “Bob”} — and you never know why your data looks wrong.
BOM characters. Some text editors save files with an invisible byte-order mark at the start. Most JSON parsers choke on it. If your JSON looks perfect but refuses to parse, this is often the reason. Save the file as UTF-8 without BOM.
Hidden whitespace from copy-paste. Copying JSON from a PDF, Word doc, or Slack message often introduces non-breaking spaces (U+00A0) that look identical to normal spaces but break the parser. If your JSON works when you retype it but fails when pasted — this is why.
The Fastest Way to Debug Any JSON Error
When you’re stuck, here’s the four-step routine that’ll solve nearly any JSON problem:
1. Paste your JSON into a validator. Ours runs entirely in your browser, so your data never leaves your machine. It highlights the exact line and character where parsing breaks.
2. Read the error message literally. “Unexpected token } at position 47” means: at character 47, the parser found a } when it was expecting something else. Count to position 47, or just look at the highlighted spot.
3. Format it first, then read it. Minified JSON hides errors. Beautified JSON exposes them. Get in the habit of running broken JSON through a beautifier before you even try to debug it.
4. Check the four most common culprits first: trailing commas, single quotes, missing commas between properties, and mismatched brackets. That covers 80% of JSON errors you’ll ever encounter.
JSON errors are annoying, but they’re consistent. Once you’ve seen these ten patterns a few times, you’ll spot them in two seconds flat. Promise.
