JSON (JavaScript Object Notation) is the standard for web communication, data exchange, and configuration files. RFC 8259 defines it with zero flexibility: strict syntax, strict types, strict structure. Machine predictability over human convenience.

That strictness means a single misplaced character triggers a syntax error (invalid json or unexpected token in json), breaking builds, crashing applications, or halting data pipelines.

This guide covers the most common JSON syntax anomalies, how to interpret error messages across environments, and a systematic workflow for safe debugging.

Common JSON Syntax Anomalies

Most JSON errors stem from manual editing mistakes or flawed serialization. Each example below shows the broken input and the fix.

1. Trailing Commas

RFC 8259 defines commas strictly as separators between elements. A trailing comma after the last item is legal in JavaScript but causes standard JSON parsers to expect another element, leading to a parsing failure when they encounter } or ].

Before (Invalid JSON):

{
  "database": "production",
  "pool_size": 10,
  "supported_drivers": [
    "pg",
    "mysql",
  ]
}

After (Valid JSON):

{
  "database": "production",
  "pool_size": 10,
  "supported_drivers": [
    "pg",
    "mysql"
  ]
}

2. Missing Quotes Around Keys

While JavaScript allows unquoted object keys, JSON demands that every property name is a string enclosed in double quotes.

Before:

{
  host: "127.0.0.1",
  port: 8080
}

After:

{
  "host": "127.0.0.1",
  "port": 8080
}

3. Using Single Quotes (Apostrophes)

JSON strictly requires double quotes (") for both keys and string values. Single quotes (') are not recognized.

Before:

{
  'auth_method': 'bearer',
  'token': 'a1b2c3d4'
}

After:

{
  "auth_method": "bearer",
  "token": "a1b2c3d4"
}

4. Unescaped Characters and Paths

Control characters (like tabs or newlines) cannot appear raw in JSON strings; they must be escaped (\t, \n). Similarly, using a single backslash for Windows file paths without escaping it (\\) will break the document.

Before:

{
  "file_path": "C:\Users\App\config.json",
  "description": "System logs:\nStatus: Ok"
}

After:

{
  "file_path": "C:\\Users\\App\\config.json",
  "description": "System logs:\\nStatus: Ok"
}

5. Runtime Type Leaks: NaN, undefined, Infinity

Serializing data from JS or Python can leak internal runtime types into JSON output. NaN, undefined, and Infinity are not part of the JSON specification. Convert unassigned values to null, and represent infinite values as large numbers or handle them before serialization.

Before:

{
  "execution_time": NaN,
  "session_token": undefined,
  "load_limit": Infinity
}

After:

{
  "execution_time": null,
  "session_token": null,
  "load_limit": 1.7976931348623157e+308
}

6. Comments in Data Structures

Standard JSON does not support comments (// or /* */). Trying to add them to network payloads or standard configs will crash the parser.

Before:

{
  // Payment gateway URL
  "gateway_url": "https://api.payments.com",
  /* Fallback port */
  "backup_port": 8443
}

After:

{
  "gateway_url": "https://api.payments.com",
  "backup_port": 8443
}

7. The Hidden BOM (Byte Order Mark)

Some text editors (like Windows Notepad) insert a hidden byte sequence (0xEF, 0xBB, 0xBF or \ufeff) at the start of a file to indicate UTF-8 encoding. Many modern tools (like Vite, Rust deserializers, or NPM) will fail immediately when encountering this invisible character at position 0. You must save files with "UTF-8 without BOM" or strip the BOM programmatically.

8. Illegal Number Formats

JSON imposes strict rules on numbers. Leading zeros for integers (e.g., 015) and trailing decimal points without fractional parts (e.g., 4.) are illegal. Use 15 and 4.0 respectively.

Try the tool →

Understanding JSON Diagnostics

Different environments report JSON errors in different formats. Knowing what to look for saves time.

JavaScript (V8 Engine / Node.js)

Older versions of V8 returned an absolute character index (e.g., SyntaxError: Unexpected token X in JSON at position 124), making it hard to find errors in large payloads.

Modern Node.js (v21+) points directly to the exact line and column: SyntaxError: Unexpected token '}',... is not valid JSON

Tip: An error like Unexpected token < in JSON at position 0 almost always means your app received an HTML error page (like a 404 or 500 response starting with <!DOCTYPE html>) instead of JSON.

Python

Python’s json.decoder.JSONDecodeError provides detailed metadata:

  • msg: The issue description (e.g., Expecting property name enclosed in double quotes).
  • lineno & colno: The precise line and column of the defect.
  • pos: The raw character index.

JQ (Unix/Linux)

The command-line processor jq stops immediately on bad syntax, throwing errors to STDERR like: jq: parse error: Invalid numeric literal at line 1, column 7 (often caused by single-quoted strings that jq tries to read as numbers).

Tip: To safely parse logs line-by-line while ignoring broken JSON, use: jq -R 'fromjson? | .' logs.json.

The Developer Workflow for Fixing JSON

  1. Extract Raw Bytes: Never debug a corrupted JSON file based on a variable logged from inside your app's code. Capture the raw text response before JSON.parse is called to see what the parser actually received.
  2. Bisect Large Payloads: If the JSON is massive, cut it in half. Test each half to isolate the block throwing the error.
  3. Format & Beautify: Expanding minified JSON to a readable, indented format exposes mismatched brackets and structural issues.
  4. Validate Locally: Paste the isolated structure into a dedicated, client-side tool that highlights the exact failing token.

The Danger of Online JSON Validators

When a broken JSON response needs formatting, many developers reach for a free online formatter. Most of these tools operate server-side: your payload gets sent via HTTP POST to an external server. Every API key, database credential, or OAuth token you paste becomes part of someone else's server logs.

Security researchers have repeatedly documented cases of sensitive data (production credentials, AWS keys, PII) being recoverable from the logs of popular formatting services. The attack surface is straightforward: if the tool sends your input to a server, that server stores it.

Use 100% Client-Side Tools

To eliminate this risk, only use formatters that run entirely in your browser sandbox. Our JSON Formatter processes everything locally using JavaScript.

  • Zero data transfer: Nothing is ever sent to a server.
  • Offline capable: It works even if you disconnect from the internet.
  • Verifiable: You can open your network tab to prove no data leaves your machine.

FAQ

What does "Unexpected token < in JSON at position 0" mean?
It means the parser expected a { or [, but received a <. This typically happens when an API call fails with a 404 or 500 error, and the server returns an HTML error page instead of a JSON payload. Always verify the Content-Type and response status.

Are comments allowed in JSON files?
No. RFC 8259 strictly prohibits comments. If you need comments for configs, you must use extended formats like JSONC (used by VS Code) or JSON5, which require specialized parsers.

How do I fix a BOM error?
A Byte Order Mark (\ufeff) is an invisible character at the start of a file. Save your file in your code editor using the explicitly named "UTF-8 without BOM" encoding, or trim the first character programmatically if it matches the BOM sequence.

Why are NaN and Infinity rejected?
They are JavaScript-specific concepts, not standard numerical data. JSON only supports decimal numbers. You must serialize these edge cases as null or explicit string values.