Why Your JSON Keeps Breaking (And How a Formatter Saves You)

It usually happens at the worst possible time. You're twenty minutes before a deployment window, the API integration is almost done, and then you get it — a cryptic SyntaxError: Unexpected token buried in a stack trace that tells you almost nothing useful. The JSON is broken. Again.

If you've spent more than a month writing code that talks to APIs, config files, or databases, you already know this feeling. JSON is everywhere. It's the lingua franca of the modern web, and it is remarkably easy to get wrong in ways that take way longer to debug than they should.

Let's go through the real culprits — the specific, annoying mistakes that break JSON in production — and talk about how a proper formatter and validator catches them before they become your problem at 11pm.

The Usual Suspects

1. The Trailing Comma That Ruins Everything

This one gets almost everyone who comes from a JavaScript background, and honestly it makes sense why. Modern JavaScript (and Python, and Ruby) are totally fine with trailing commas in arrays and objects. It's a quality-of-life thing — you can reorder items without touching the last line.

But JSON? JSON hates it with a passion.

{
  "name": "Pawan",
  "role": "developer",
  "skills": ["Python", "React", "SQL",]
}

That comma after "SQL" is completely harmless in a JS object literal. In JSON, it's a parse error. Every major JSON parser — the browser's JSON.parse(), Python's json.loads(), Java's Jackson, Go's encoding/json — will refuse to read this. No warnings, no fallback. Just an error.

The sneaky part is how this happens. You're editing a config file, you delete the last item in a list, and the comma that used to be in the middle is now dangling at the end. Or you paste code from a JS file. Or a code generator that wasn't quite JSON-aware emits one. It's not a stupid mistake — it's a structural mismatch between two formats that look almost identical.

2. Unescaped Quotes Inside String Values

Imagine you're storing a user's message in JSON:

{
  "message": "He said "hello" and left."
}

The parser sees the quote before "hello" and assumes the string ended there. Everything after that is garbage syntax as far as it's concerned. You need to escape the internal quotes:

{
  "message": "He said \"hello\" and left."
}

This becomes especially painful when you're dynamically building JSON strings through concatenation instead of using a proper serializer. Hand-rolled JSON construction is one of those things that works fine until the data contains a quote, a newline, or a backslash — and then it detonates.

The fix here isn't just escaping. It's never building JSON by concatenating strings in the first place. Let your language's JSON library handle serialization. But if you've inherited code that doesn't do that, a formatter will at least tell you where the problem is.

3. Single Quotes Instead of Double Quotes

Another JavaScript spillover. In JS, {'key': 'value'} is valid. In JSON, it's not. The spec is explicit: strings must use double quotes. Single quotes are not an acceptable alternative, they're a syntax error.

// This is NOT valid JSON
{
  'database': 'postgres',
  'port': 5432
}

This shows up constantly in configs that started life as Python dictionaries or JavaScript object literals and got copy-pasted into a .json file without conversion. The file looks fine visually. The parser disagrees.

4. Comments Inside JSON

JSON does not support comments. Not // comments. Not /* */ comments. Nothing. If you're writing a config file and you want to explain what a field does, you simply cannot do it inline in pure JSON.

This frustrates a lot of developers, which is exactly why formats like JSONC (JSON with Comments) and JSON5 exist. But if your parser expects strict JSON and it gets a // somewhere, it will fail.

The solution some people reach for is adding a dummy field like "_comment": "this is why this exists". It's ugly but it works. The cleaner solution for config files is switching to TOML or YAML if comments matter that much to you. But either way, you need to know that vanilla JSON parsers will choke on any comment syntax.

5. Numbers That Aren't Actually Numbers

JSON has specific rules about numeric values. NaN is not valid JSON. Infinity is not valid JSON. -Infinity is not valid JSON. Leading zeros on integers (like 007) are not valid.

When you're serializing data from Python, for instance, a float('nan') or float('inf') will cause json.dumps() to either throw an error or — and this is worse — silently emit invalid JSON depending on your settings. That invalid JSON then gets consumed somewhere downstream, and the error appears far from the source.

6. Encoding Issues and Invisible Characters

This one is subtle and genuinely hard to spot without tooling. Sometimes JSON breaks because of invisible characters — a byte-order mark (BOM) at the start of a file, a non-breaking space that looks like a regular space, control characters that snuck in from a copy-paste out of a PDF or Word document.

Your text editor won't show you the problem. The parser error message will point to a character position that seems perfectly normal when you look at it. A good formatter will highlight or strip these invisible characters, which saves you the forty-five minutes of staring at something that looks completely fine.

Where Formatters Actually Help

A JSON formatter does more than make your JSON pretty. The good ones perform validation as a first step — they parse the structure and report exactly what's wrong before they even attempt to reformat anything.

Here's what you get from running your JSON through a proper formatter or validator:

Precise error locations. Instead of "invalid JSON," you get "unexpected token on line 47, column 12." That's the difference between a thirty-second fix and a ten-minute hunting expedition.

Visual structure that exposes the problem. When JSON is minified or poorly indented, a structural bug like a missing closing bracket is nearly impossible to see. Reformatting collapses the ambiguity. You can see the nesting at a glance, and the missing bracket jumps out.

Automatic escaping suggestions. Some formatters will highlight strings that contain unescaped characters and either warn you or offer to fix them automatically.

Schema validation. Beyond just being valid JSON, the data might be structurally wrong for your use case — a required field missing, a string where a number is expected. Tools that support JSON Schema validation let you catch these semantic errors, not just syntactic ones.

Integrating This Into Your Workflow

The most effective place to catch JSON errors is before they ever reach your runtime. A few practical approaches:

Editor plugins. If you're using VS Code, the built-in JSON support will underline errors in real time. For stricter validation (including schema validation against a JSON Schema file), the "Even Better TOML" and "YAML" extensions give you a sense of what's possible; there are equivalent JSON Schema plugins that do the same for JSON.

Pre-commit hooks. Adding a JSON lint step to your pre-commit hook means that broken JSON never makes it into your repository. A one-liner using Python works: python -m json.tool yourfile.json > /dev/null. If it exits non-zero, the commit is blocked.

CI pipeline checks. For projects with multiple JSON config files, a CI step that validates all of them on every pull request gives you a safety net even if someone bypasses the pre-commit hook.

Online formatters for quick checks. When you're debugging something fast and don't want to open a terminal, a browser-based JSON formatter is genuinely useful. Paste the JSON, click validate, get the error location in under a second. These tools also let you minify or prettify for readability without any setup.

The Bigger Picture

JSON errors feel trivial — and individually they are — but they have a way of surfacing at the absolute worst moments. The config file that worked fine on your machine is malformed in the production environment because someone edited it by hand and left a trailing comma. The API response your code parses is fine ninety-nine percent of the time, but one edge case includes a quote in a user's name and the whole thing collapses.

The fix is not to memorize every JSON edge case. The fix is to stop trusting your eyes and start trusting tooling. Run your JSON through a formatter before it runs through your code. Set up validation in your editor. Add a lint step to your CI. These are small habits that eliminate an entire category of bugs.

The JSON spec is only about ten pages long. It's strict by design — no trailing commas, no comments, no single quotes, double quotes only, no NaN. That strictness is actually a feature: it makes JSON completely unambiguous. The problem is that humans write ambiguous things by accident, and we need tools to catch us.

A formatter is not a luxury. For any project where JSON matters — and these days, that's most projects — it's just part of the job.