JSON Formatter: 5 Common Mistakes Developers Make

If I had a dollar for every time a junior dev pasted broken JSON into our API and stared blankly at a 500 error, I'd have enough to buy a very nice coffee machine. Maybe two.

JSON seems simple on the surface—key-value pairs, curly braces, done. But it's deceptively picky about syntax, and the errors it throws are about as helpful as a compass pointing south. Here are the five mistakes I see most often, with actual examples of what goes wrong and how to fix it.

1. Trailing Commas — The #1 JSON Killer

❌ WRONG

This one catches almost everyone who's used to JavaScript. In JS, trailing commas are fine. In JSON? They'll break your parser every time.

{
  "name": "Alice",
  "age": 30,
  "email": "[email protected]",
}

See that comma after the last value? That's a syntax error. The JSON spec doesn't allow it, period. Your parser will choke with something like SyntaxError: Unexpected token } in JSON at position 48 or unexpected end of JSON input.

✅ FIXED

{
  "name": "Alice",
  "age": 30,
  "email": "[email protected]"
}

Remove the trailing comma. Or better yet, run your JSON through a formatter that catches this automatically. Most decent formatters will highlight the offending comma for you.

Pro tip: many code editors let you enable "trailing comma removal on save" as part of your linter config. Set that up once and you'll basically never hit this again.

2. Single Quotes Instead of Double Quotes

❌ WRONG

Another one that trips up JavaScript developers. In JS, both 'string' and "string" work. JSON only accepts double quotes.

{
  'name': 'Alice',
  'active': true
}

This fails with Expected double-quoted property name or similar, depending on your parser. Sometimes the error message is even vaguer, which is fun.

✅ FIXED

{
  "name": "Alice",
  "active": true
}

Double quotes for keys, double quotes for string values. No exceptions. Not for the values, not for the property names. Everything that's a string gets double quotes.

I once saw a config file where someone had written the entire thing with single quotes, then spent an hour debugging why their Go application couldn't parse it. The Go JSON parser's error messages aren't exactly detailed. Don't be that person.

3. Comments Don't Exist in JSON

❌ WRONG

You want to add a note to your JSON file? Tough luck. The JSON spec doesn't support comments. This surprises people every single time.

{
  // User configuration
  "name": "Alice",
  "theme": "dark" // can be "light" or "dark"
}

This will fail silently or throw a parse error. JSON.parse() in JavaScript will give you Unexpected token / in JSON at position 2. Not obvious at all if you're not looking for it.

✅ FIXED

You have three options:

Use a JSON5 parser — JSON5 supports comments, trailing commas, and single quotes. Libraries exist for most languages.
Add a "_comment" key — Ugly but effective: "_comment": "Set theme to dark or light". Just remember to strip it before sending to production APIs.
Keep docs separate — Maintain a README or comment file alongside your JSON. Less convenient but keeps the JSON clean.

I've seen production config files with "// legacy field, do not remove" as an actual key name. Please don't do that.

4. BOM and Encoding Nightmares

❌ WRONG

This is the most insidious JSON error because everything looks fine visually. You open your file in Notepad, it looks perfect. You try to parse it, and... nothing works.

The culprit is usually a BOM (Byte Order Mark) at the beginning of the file. Some editors—especially on Windows—add a UTF-8 BOM (EF BB BF) when saving files. Your JSON parser sees those three invisible bytes before the opening { and has no idea what to do with them.

// Looks like this to you:
{ "name": "张三" }

// But the actual bytes start with EF BB BF, making the parser see:
[byte-order-mark]{ "name": "张三" }

Error message? Something useless like Unexpected token \u00ef in JSON at position 0. Position 0. The very first byte. Good luck debugging that at 2 AM.

✅ FIXED

Save without BOM — In VS Code, check the encoding indicator in the bottom-right corner. If it says "UTF-8 with BOM," click it and switch to "UTF-8."
Use a hex editor to check if BOM bytes are present.
Strip BOM programmatically — If you're consuming API responses, strip the first 3 bytes if they match EF BB BF before parsing.

Related issue: files saved as something other than UTF-8 (like GB2312 or Windows-1252) will cause parse errors when they contain non-ASCII characters. Always ensure your JSON files are saved as plain UTF-8 without BOM.

5. Nesting So Deep It Becomes Unmaintainable

⚠️ NOT A SYNTAX ERROR, BUT SHOULD BE

Technically this won't throw a parse error. But it'll cause you way more pain than any syntax bug.

{
  "company": {
    "departments": {
      "engineering": {
        "teams": {
          "frontend": {
            "members": {
              "alice": {
                "role": "senior",
                "skills": ["React", "TypeScript"],
                "manager": {
                  "name": "Bob",
                  "role": "tech-lead",
                  "manager": {
                    "name": "Carol",
                    "role": "VP"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

If you need to access Alice's skills, you're writing data.company.departments.engineering.teams.frontend.members.alice.skills. Good luck maintaining that. Miss one level and you're debugging a Cannot read property of undefined error for 20 minutes.

✅ FLATTEN IT

Restructure your data to avoid deep nesting. A few approaches:

Use arrays with references — Separate entities into arrays and use IDs to link them, like a relational database.
Flatten key paths — Use dot-separated keys: "frontend.alice.role".
Split into multiple files — No rule says all your data must live in one JSON blob.

As a rule of thumb, if you're nesting more than 3-4 levels deep, you probably need to rethink your data structure. Your future self will thank you.

Quick Fix: Use a Real JSON Formatter

Most of these mistakes become trivial if you run your JSON through a proper formatter and validator before using it. A good formatter will catch trailing commas, highlight encoding issues, and flag syntax problems instantly.

That's exactly why we built the Vaultool JSON Formatter—it validates, formats, and points out errors right in your browser, without uploading your data anywhere. Paste broken JSON in, see exactly what's wrong, fix it, copy the clean version out.

Paste your JSON, get instant error highlighting and clean formatting. No upload needed.

Try it free on Vaultool →