JSON Unexpected Token: Linting Saved My Production Build

Why did my JSON suddenly throw an "Unexpected token" error in production?

That's the question I found myself asking at 2:47 AM on a Thursday, staring at a CI/CD pipeline that had been green for six weeks and then, without warning, turned red. The culprit was a single JSON configuration file — 1,847 lines of environment-specific settings that three different engineers had touched that day. The error message was almost mocking in its brevity: SyntaxError: Unexpected token } in JSON at position 1432.

I'm sharing this because if you've landed here, you're probably in a similar spot. You're working with JSON — maybe config files, API payloads, or data exports — and something that should parse cleanly is throwing a token error that makes no immediate sense. Let me walk you through what I learned that night and in the weeks that followed, because the fix was not what I initially expected.

What exactly is an "unexpected token" in JSON?

JSON is a strict, unforgiving format. Unlike JavaScript, it doesn't tolerate trailing commas, comments, single quotes, or unquoted keys. When a parser encounters something that violates the spec, it tells you the token it found was not what it expected at that position. Hence: unexpected token.

In my case, position 1432 contained a closing curly brace } that appeared one line too early. A colleague had added a new configuration block and forgotten a comma on the preceding entry. The parser saw } where it expected either a comma or another key-value pair, and it stopped.

The error message tells you where the parser got confused. It rarely tells you why. That gap between "where" and "why" is where most developers lose 20 to 40 minutes hunting through a file manually.

What are the most common causes of unexpected token errors?

After that incident, I audited every JSON-related failure we'd had over the previous quarter. I found 14 instances. Here's what actually causes these errors in practice — not in theory, but in real files edited by real humans under deadline pressure.

Trailing commas

This was our single most frequent offender, responsible for 6 out of 14 failures. Someone adds a new property to the end of an object, and the previous line — which used to be last and therefore didn't need a comma — now does. It's easy to miss, especially in large files.

Single quotes instead of double quotes

JSON requires double quotes around strings and keys. If you're switching between JavaScript and JSON frequently (as we were with our Node.js config files), muscle memory kicks in and you type 'value' instead of "value". This accounted for 3 of our 14 errors.

Unquoted property keys

In JavaScript, {name: "server"} is valid. In JSON, it's not. You must write {"name": "server"}. This caused 2 failures, both in files where someone had copied a JS object literal and saved it as JSON.

Comments left in the file

JSON doesn't support comments. No //, no /* */. Yet developers add them constantly, especially in configuration files where you want to explain what a setting does. We had 2 failures from this.

Invisible characters and encoding issues

This was the nastiest one. A file exported from a spreadsheet tool contained a BOM (Byte Order Mark) at the beginning, and the parser choked on it. The error pointed to position 0, which was deeply confusing until we checked the file's hex output. One single failure, but it took over an hour to diagnose.

How does a JSON linter catch these errors before they cause damage?

Here's where the story shifts from diagnosis to prevention. After the 2:47 AM incident, I integrated a JSON linter into our pre-commit hook and our CI pipeline. The results were immediate and measurable: in the following quarter, we had zero JSON-related deployment failures, down from the 14 I'd found in the previous one.

A JSON linter does something simple but powerful: it parses your JSON before runtime does. If the parse fails, it tells you exactly what's wrong, in human-readable language, before the file ever reaches production. Some linters go further and enforce style consistency — sorted keys, consistent indentation, no trailing commas — but the core value is validation.

The key insight is when you lint. Linting at runtime, when your application tries to parse the file, is too late. The error has already propagated. Linting in your editor, as you type, is better. Linting in a pre-commit hook and in CI is best, because it catches problems introduced by merge conflicts, copy-paste errors, and automated transformations that no human eye reviewed.

What's the fastest way to find and fix an unexpected token error?

When you're staring at an error right now and need to fix it, here's the approach that works. I've refined this over dozens of incidents.

Step 1: Go to the position in the error message. If it says position 1432, count to character 1432. Most editors don't show character positions by default, but many JSON tools and online validators do. Paste your JSON into a validator, and it will highlight the exact location.

Step 2: Look at the character before the unexpected token. The error is usually not at the token itself but at what precedes it. A missing comma on the previous line. A missing closing bracket earlier in the file. The unexpected token is the symptom; the cause is upstream.

Step 3: Check for the usual suspects. Scan backward from the error position for trailing commas, single quotes, unquoted keys, or comments. These four categories cover the majority of real-world failures.

Step 4: If nothing looks wrong visually, check for invisible characters. Open the file in a hex editor or use a tool that displays non-printing characters. BOM markers, zero-width spaces, and smart quotes copied from documentation can all trigger unexpected token errors that are invisible in a normal editor.

How do you prevent unexpected token errors in collaborative JSON workflows?

The deeper lesson from my 2:47 AM experience wasn't about any single error. It was about workflow. Three engineers had edited the same JSON file, and no one had validated the final result before it shipped. The file passed review because the diff looked reasonable, but the combined changes created a structural problem that no individual diff revealed.

If you're working in a team that edits shared JSON files — configuration, API schemas, translation files, fixture data — here's what I recommend based on what actually worked for us.

First, validate JSON in your editor. Most modern editors either support JSON validation natively or through extensions. Errors appear as you type, before you even save. This is the cheapest, fastest layer of defense.

Second, add a JSON validation step to your pre-commit hook. We used a simple script that ran every .json file through a parser and rejected the commit if parsing failed. It added about 0.3 seconds to each commit and saved us from pushing broken JSON to the repository at least a dozen times in the first month.

Third, lint in CI. Even with editor validation and pre-commit hooks, things slip through — usually due to merge conflicts resolved incorrectly or automated scripts that modify JSON programmatically. A CI step that validates all JSON files in the repository is your last line of defense before code reaches production.

Why JSON validation tools matter more than memorizing the spec

I spent years thinking I could just "be careful" with JSON. The truth is, careful people make syntax errors in JSON because the format is designed for machines, not humans. Trailing commas are the most natural thing in the world to add when you're editing a list. Comments are how humans make sense of configuration. Single quotes are faster to type. None of these are allowed in JSON, and no amount of care will fully prevent them.

The shift that mattered for me — and that I'd recommend to anyone reading this — was moving from "I'll be more careful next time" to "I'll let a tool catch this so I don't have to be." A JSON linter doesn't get tired. It doesn't skip a line because it's 2 AM. It doesn't assume the last person to edit the file left it in a valid state. It just checks, every time, and tells you the truth.

That Thursday night cost me roughly three hours of sleep and delayed a deployment by four hours. The fix — a 12-line pre-commit hook and a linter in CI — took 20 minutes to set up and has prevented every similar incident since. If you're dealing with unexpected token errors, stop debugging them one at a time and start preventing them at the source.