Every Windows developer has encountered the moment: a script halts, a service won't start, and the log screams "SyntaxError: Unexpected token < in JSON at position 0". The JSON parse error is the ultimate roadblock—confounding, yet often trivial to fix once you know where to look. Drawing on the distilled wisdom from Windows Report's practical guide and deeper community diagnostics, this article lays out a bulletproof, safe-for-production workflow that turns JSON debugging from panic into a systematic five-minute routine.

The Anatomy of a JSON Parse Error

At its core, JSON (JavaScript Object Notation) is a strict serialization format governed by a simple but unforgiving grammar. When a parser—whether JavaScript's JSON.parse, Python's json.loads, or a C# JsonSerializer—encounters bytes that violate that grammar, it aborts and throws a SyntaxError. The error message always includes a token and a position, which are your first clues. For example, "Unexpected token } in JSON at position 47" tells you the parser expected something else at character 47, but found a closing brace.

What makes these errors particularly maddening on Windows is the ecosystem's diversity: you might be editing JSON in Notepad, Notepad++, or Visual Studio Code; consuming APIs from PowerShell scripts or .NET applications; or parsing configuration files that were auto-generated by a legacy tool that inserts hidden byte-order marks (BOM). The error can originate from a single misplaced comma or from a server returning an HTML error page instead of a JSON payload.

The Windows Report guide categorizes the typical outcomes plainly: browser exceptions, applications refusing to start, or services returning 4xx/5xx codes because they can't decode a request body. These symptoms all share one root cause: bytes on the wire or on disk don't match what the parser expects.

Top Culprits That Break Parsers

Before you dive into fixing, categorize the problem. The most frequent offenders fall into three buckets:

  • Syntax blunders: trailing commas, unquoted property names, missing colons, or using single quotes instead of double quotes. JSON is stricter than JavaScript object literals; a trailing comma after the last array element is illegal.
  • Encoding and invisible characters: a byte-order mark (0xFEFF) at the start of the file, saved by editors like Windows Notepad when set to "UTF-8 with BOM," will cause parsers to choke at position 0. Non-printable control characters introduced by copy-paste from rich-text documents also land in this category.
  • Wrong content returned by servers: exactly the "Unexpected token <" scenario. The server sent an HTML error page, a redirect, or plain text, but the client blindly calls JSON.parse on the response body.

Once you've ruled out the obvious syntax issues, focus on these hidden gremlins. They account for over 80% of real-world JSON parse errors on Windows platforms.

Step 1: Validate Syntax Instantly

Your first move is always the same: open the JSON in a capable editor. Visual Studio Code (VS Code) is the de facto standard for Windows developers. It ships with built-in JSON validation that highlights problems in the Problems pane the moment you open a .json file. Wavy underlines, error badges, and instant feedback make it the fastest way to spot a stray comma or a missing quote. For those who prefer a lighter tool, Notepad++ with the JSON Viewer plugin performs similarly, albeit with slightly less polish.

If you're working with a raw string from a clipboard, paste it into JSONLint.com or any online validator. These tools pinpoint the exact position and often suggest fixes. The Windows Report article deems this the single most effective step—and it's hard to argue. Validation turns guesswork into a deterministic repair.

Step 2: Exterminate Syntax Errors

Once the linter tells you what's wrong, fix it methodically:

  • Switch all keys to double quotes (no single quotes, no bare words).
  • Remove trailing commas anywhere, including before a closing brace or bracket.
  • Balance every { with a }, and every [ with a ].
  • Replace JavaScript expressions like undefined, function(){}, or new Date() with JSON-legal values: null, a string, or an ISO date string.
  • Ensure numeric values don't have leading zeros (e.g., 07 is invalid; use 7).

A common pitfall: configuration files originally written as JavaScript objects (e.g., in a Node.js module) will work if read via require but fail under JSON.parse. The two formats look identical but aren't. Run your file through a strict validator to catch every discrepancy.

Step 3: Check Encoding and BOM—the Invisible Byte That Kills Everything

You've fixed every visible character, yet the parser still fails at position 0. The file is most likely saved with a byte-order mark. The BOM is a Unicode character (U+FEFF) placed at the beginning of a text stream to signal endianness. JSON standards explicitly forbid it, but Windows tools like classic Notepad and some PowerShell redirections tack it on by default.

In VS Code, glance at the status bar: it displays the current encoding. If it says "UTF-8 with BOM" or "UTF-16 BE", click it and select "Save with Encoding" → "UTF-8" (without BOM). In Notepad++, the Encoding menu offers a "Encode in UTF-8" option that strips the BOM. For command-line aficionados, a PowerShell script can read the file and rewrite it without the BOM:

$text = Get-Content -Path 'file.json' -Encoding UTF8 | Out-String
$text.TrimStart("`u{FEFF}") | Set-Content -Path 'clean.json' -Encoding UTF8

After stripping the BOM, also delete any leading whitespace or control characters that might have slipped in. A quick test: open the file in a hex editor (or simply Get-Content -Encoding Byte) and verify the first byte is not 0xEF 0xBB 0xBF.

Step 4: Make Sure the Server Actually Returned JSON

If the error originated from a web API call, the problem is almost certainly server-side. Open your browser's DevTools (F12), switch to the Network tab, and reproduce the failing request. Click on the request to inspect the Response tab. If you see HTML tags, you've found the culprit. The server sent an error page (status 401, 403, 500) or a redirect instead of JSON.

Also check the response's Content-Type header. It should read application/json (or application/json; charset=utf-8). If it's text/html, the client is right to complain when you try to parse it as JSON.

For Windows-specific scenarios: when automating with PowerShell's Invoke-RestMethod, the cmdlet automatically parses JSON if the content-type is correct. If the server returns HTML, Invoke-RestMethod throws a misleading error. Use Invoke-WebRequest instead to examine the raw content before parsing.

Server-side fixes include:
- Configuring the web framework (ASP.NET, Node/Express, etc.) to return JSON for API error responses. In ASP.NET Core, you can use a global exception handler that sets Content-Type: application/json and writes a consistent JSON error object.
- Ensuring authentication middleware doesn't redirect API clients to login pages—return a 401 with a JSON body.
- Checking proxy or load-balancer rules that might alter content types.

Step 5: Clear Cache and Retest

Cached, stale, or corrupted responses are a notorious source of transient JSON errors. A partially downloaded file stored by the browser, or an application cache that holds an old version of a config file, will appear valid on disk but fail at parse time.

Perform a hard refresh first: Ctrl+F5 in most browsers, Cmd+Shift+R on Mac. If that doesn't work, clear the browser cache entirely (Settings → Privacy → Clear browsing data). For desktop or mobile apps, locate the app's cache directory—often under %APPDATA% on Windows—and delete the relevant JSON files, then restart the app.

Testing in a private/incognito window rules out extensions and cached redirects. The Windows Report guide specifically calls out Firefox's JSON viewer quirks; sometimes the built-in viewer caches old data even when the server has changed. Disabling the viewer or using a different browser can confirm this.

Step 6: Update or Reinstall the Software

Older versions of parsers can exhibit non-standard behavior. For instance, early versions of some .NET JSON libraries struggled with large floating-point numbers or deeply nested structures. If your JSON passes all validation but still fails in a specific app, check for updates. In the Windows world, this might mean upgrading to the latest Windows build, the newest Visual Studio, or the most recent NuGet package.

When the problem affects a system component (e.g., a Windows service that reads a JSON config), running DISM /Online /Cleanup-Image /RestoreHealth or sfc /scannow can repair corrupted system files. This is rare but occasionally necessary after a botched update or disk error.

Real-World Debugging: The HTML Trap

To see the workflow in action, consider this common scenario: a line-of-business Windows desktop app calls an internal API and throws "Unexpected token <".

  1. Open DevTools (or Fiddler/Charles if it's a desktop app) and capture the failing request.
  2. The response status is 401 Unauthorized. The body is <html><head><title>Login Required</title>.... The Content-Type header reads text/html.
  3. The authentication token had expired. The client code did not check the status code before parsing, so it attempted to parse the login page as JSON.
  4. Fix: update the client to inspect response.status first. On the server, change the 401 response to return { "error": "unauthorized" } with Content-Type: application/json.

This five-minute diagnosis saves hours of hair-pulling. Always inspect the raw payload before blaming the parser.

Preventing Nightmares: Linting, Contracts, and Testing

The safest fix is one that never needs to happen. Integrate JSON validation into your development pipeline:

  • CI/CD linting: Use a linter like jsonlint (Node) or a pre-commit hook that runs Python's json.tool to validate every JSON file on check-in.
  • Schema validation: Define a JSON Schema for your API responses and configuration files. Tools like ajv can validate payloads early, catching structural regressions before they reach production.
  • Server-side hygiene: Always set Content-Type: application/json and return JSON error objects. Never let an API endpoint emit an HTML error page.
  • Programmatic generation: Avoid hand-editing production JSON. Generate it from trusted sources—serialize a data structure in your backend code instead of concatenating strings.
  • Robust client handling: Never call JSON.parse blindly. Wrap it in a try-catch, and if it fails, log the raw string (truncated if necessary) for post-mortem analysis. Check the content-type header before parsing.
  • Encoding discipline: Configure your editor and build scripts to save everything as UTF-8 without BOM. A .editorconfig file with charset = utf-8 and insert_final_newline = true enforces this team-wide.

The Windows Report Primer: What It Gets Right, and Where You Need More

The Windows Report guide serves as an excellent triage checklist for everyday users. It correctly emphasizes validation, caching, and using accessible tools like Notepad++ and online linters. For many, those steps alone will resolve the issue.

However, as the community discussion around the article notes, the guide skims over server-side remediation and encoding nuances. A developer who merely clears the cache and validates the file may still face the same error if the server keeps serving HTML or the file carries a BOM. This article fills those gaps with explicit encoding checks, DevTools inspection steps, and server configuration advice.

When to Escalate

Sometimes, the error isn't yours to fix. If a vendor-supplied JSON file or a Windows OS component repeatedly fails validation after you've checked encoding and syntax, contact the vendor. Do not attempt to modify system files—a forced fix could introduce instability.

If the problem is reproducible across multiple clients and the server returns a 500 or 502, it's a backend issue. Capture the request ID (often in a response header like X-Request-ID), attach the raw response payload, and file a ticket with the backend team. Intermittent disk corruption or network issues can also produce truncated files; run chkdsk and check network hardware if file corruption spans multiple unrelated files.

Conclusion: The Definitive 10-Minute Fix

JSON parse errors are not cryptograms—they're deterministic failures with a small set of root causes. By following this workflow—validate, fix syntax, strip BOM, inspect server responses, clear caches, and update software—you'll resolve the vast majority of cases within ten minutes. Keep the advanced checklist on hand for stubborn problems, and invest in preventative tooling. With these habits, you'll transform JSON parsing from a recurring headache into a non-issue.