JSON Unexpected Token Fix: One Real Linter Workflow

The Misconception: Trusting the Error Message's Line Number Blindly

Last Tuesday, I pushed a configuration update to our e-commerce platform's product catalog API. Within seconds, the CI/CD pipeline spat back a red error: Unexpected token } in JSON at position 247. My instinct? Jump straight to line 247, scan for a stray bracket, fix it, push again. Sound familiar? Here's the hard truth I learned that day: the line number in a JSON syntax error is rarely where the actual mistake lives. In fact, in my case, the real culprit was a missing comma on line 231 — sixteen lines earlier. I wasted 40 minutes staring at the wrong section of code because I trusted the error message like it was a GPS pin. It's not. It's more like a smoke alarm going off in a house — it tells you there's fire somewhere, but not necessarily in the room you're standing in. This is the first bad habit I had to unlearn, and if you're reading this, you probably need to unlearn it too.

Why Your Text Editor Isn't Enough

Most of us default to hunting for JSON errors in whatever code editor we're already using. VS Code, Sublime, Notepad++ — they all do basic syntax highlighting, and that's better than nothing. But here's what they consistently miss: trailing commas, single quotes masquerading as double quotes, invisible Unicode characters copied from a Slack message or Confluence page. I learned this the hard way when a colleague copied a JSON snippet from a wiki page into our config file. The editor showed nothing wrong. The parser disagreed. An online JSON linting tool would have caught that invisible zero-width space in about three seconds. My editor? Silent as a church.

The Workflow: Step-by-Step JSON Error Hunting

Let me walk you through the exact process I now use every single time I hit an unexpected token error. This isn't theoretical — it's the workflow that saved my Tuesday and has saved me countless hours since.

Step 1: Stop Editing, Start Copying

The moment you see a syntax error, resist the urge to fix it in place. Copy your entire JSON payload out of your editor and paste it into a dedicated JSON linter. Why? Because when you're editing in your working file, you're in "builder mode" — you're thinking about logic, data structure, business rules. A linter puts you in "inspector mode." It's a mental shift that matters more than you'd think. I use our site's JSON validator tool for this, but the principle applies to any reputable linter.

Step 2: Read the Actual Error, Not Just the Line Number

When the linter processes your JSON, it'll give you an error message. Read every word of it. In my case, the tool said: "Parse error on line 12: ...'discount': 0.15}-----^ Expecting 'COMMA', got '}'". That's dramatically more useful than the generic Unexpected token message from the command line. The linter told me exactly what it expected (a comma) and what it found instead (a closing brace). That's the difference between a flashlight and a floodlight.

Step 3: Walk Backward from the Error Point

Here's the technique that changed everything for me. When the linter flags position 247, don't look at position 247. Look at everything before it. JSON errors are almost always cumulative — one missing comma or extra quote early in the file cascades into a parse failure later. In my 340-line configuration file, the actual error was at position 198, but the parser didn't choke until position 247 when it tried to make sense of the structure and couldn't. Walk backward. Check each key-value pair. Look for:

• Missing commas between pairs (the #1 culprit, in my experience)
• Single quotes instead of double quotes around strings
• Trailing commas after the last item in an array or object
• Unescaped quotes inside string values
• Comments (JSON doesn't support them, no matter how much we all wish it did)

Step 4: Use the Linter's Visual Feedback

A good JSON linting tool doesn't just throw text at you. It highlights the exact character where parsing failed and often shows you the surrounding context with syntax highlighting. In my case, the tool displayed my JSON with a red marker right at the closing brace, and the preceding line was highlighted in amber — signaling that something was off with the previous entry. That visual cue is what made me look at line 231 instead of line 247. The linter essentially said, "Hey, the error is here, but the cause is probably right above." That's the kind of hint your text editor just doesn't give you.

Step 5: Fix One Thing, Re-lint Immediately

This is where most people (including past-me) go wrong. They find a missing comma, fix it, and then keep scanning for more issues before re-validating. Don't do this. Fix one thing. Paste it back into the linter. See if the error changes or disappears. Why? Because JSON errors mask each other. Once I added the missing comma on line 231, a second error surfaced on line 289 — an unescaped quotation mark in a product description string. I never would have found that second error while the first one was still active because the parser couldn't even get that far into the file. One fix at a time. Re-lint. Repeat. It feels slower, but it's actually about 3x faster than batch-fixing and guessing.

The Real Cost of Guessing

Let me put some numbers on this. That Tuesday, I spent 40 minutes hunting for the error manually before I switched to a linter. Once I opened the linter, I found the first error in under 60 seconds. The second error took another 90 seconds. Total time with the linter: about two and a half minutes. Total time without: 40 minutes and zero progress. That's a 16x improvement. If you're dealing with JSON configuration files daily — and if you're working with APIs, CI/CD pipelines, or any modern web application, you are — that multiplier adds up fast. Over a year, assuming even one JSON error per week, you're looking at roughly 32 hours saved annually. That's a full work week.

Common JSON Errors and What They Actually Mean

While we're here, let me decode a few error messages that trip people up:

"Unexpected token < in JSON at position 0"

This almost always means your "JSON" is actually HTML. Usually an error page from a server that returned a 404 or 500 response instead of the JSON you expected. Check your API endpoint, not your JSON syntax.

"Unexpected token ' in JSON"

You used single quotes somewhere. JSON requires double quotes for all strings and keys. This is the most common error I see from developers who split time between JavaScript (where single quotes are fine) and JSON (where they're not).

"Unexpected token n in JSON"

Usually means you have an unquoted keyword like null, true, or false in a place where a string was expected, or vice versa. The linter will show you exactly where the confusion is.

Building a Linter-First Habit

The lesson I took away from that Tuesday wasn't just about JSON syntax. It was about workflow. I now keep a JSON linter tab open in my browser permanently — right next to my documentation and API testing tools. Any time I write or modify a JSON file, no matter how small the change, I run it through the linter before I save. It takes five seconds. It has eliminated an entire category of errors from my work. The developers I've recommended this habit to have reported similar results. One teammate told me she caught a trailing comma in a production config file that would have taken down a service during peak hours. The linter caught it in the time it took to press Ctrl+V.

Final Thoughts from Someone Who Learned the Hard Way

JSON is deceptively simple. It's just keys, values, brackets, and braces. But that simplicity is exactly what makes it dangerous — because when something goes wrong, there's no compiler to catch it, no type system to flag it, no runtime to warn you. The parser just stops. An online JSON linting tool is the closest thing we have to a compiler for JSON, and treating it as an optional convenience rather than a mandatory checkpoint is the mistake I made for years. Don't make the same one. Paste your JSON into a linter the moment something breaks. Read the actual error message. Walk backward from the flagged position. Fix one thing at a time. Re-lint. It's not a glamorous workflow, but it's the difference between a 40-minute fire drill and a two-minute fix — and on a Tuesday afternoon with a deployment deadline looming, that difference is everything.