Common JSON Syntax Errors and How to Fix Them

If you've worked with JSON for any length of time, you've encountered the dreaded "Unexpected token" or "JSON.parse error" message. These errors can be frustrating, especially when your JSON looks correct at first glance.

In this guide, we'll walk through the most common JSON syntax errors, explain why they happen, and show you exactly how to fix them. By the end, you'll be able to debug JSON issues quickly and confidently.

Why JSON Parsing Fails

JSON has a strict syntax specification. Unlike JavaScript objects, JSON doesn't forgive small mistakes. A single misplaced comma or unquoted key will cause the entire document to fail parsing.

Here's what valid JSON requires:

Let's look at each common error and how to fix it.

1. Trailing Commas

The Error:

The Problem:

Trailing commas after the last item in an array or object are valid in JavaScript but not in JSON.

{
  "name": "John",
  "age": 30,
}

That comma after 30 will break your JSON parser.

The Fix:

Remove the trailing comma:

{
  "name": "John",
  "age": 30
}

Why This Happens:

Most code editors and JavaScript allow trailing commas, so it's easy to accidentally include them when writing or editing JSON by hand. This is the single most common JSON error.

2. Single Quotes Instead of Double Quotes

The Error:

The Problem:

JSON requires double quotes for strings. Single quotes are not valid.

{
  'name': 'John',
  'city': 'London'
}

The Fix:

Replace all single quotes with double quotes:

{
  "name": "John",
  "city": "London"
}

Pro Tip: If you're copying data from a Python dictionary or JavaScript object that uses single quotes, paste it into jsoneditor.io and use the format button. The editor will highlight exactly where the syntax errors are.

3. Unquoted Keys

The Error:

The Problem:

In JavaScript, object keys don't need quotes. In JSON, they always do.

{
  name: "John",
  age: 30
}

The Fix:

Add double quotes around all keys:

{
  "name": "John",
  "age": 30
}

4. Comments in JSON

The Error:

The Problem:

JSON does not support comments. This surprises many developers.

{
  "name": "John",
  // This is the user's age
  "age": 30
}

The Fix:

Remove all comments:

{
  "name": "John",
  "age": 30
}

Workarounds for Comments:

If you need to document your JSON, you have a few options:

1. Use a _comment field (not ideal but works):

{
  "_comment": "User profile data",
  "name": "John",
  "age": 30
}

1. Use JSON5 or JSONC format if your tooling supports it
2. Keep documentation in a separate file
3. Consider using YAML instead, which supports comments natively. See our guide on how to convert JSON to YAML.

5. Invalid Escape Sequences

The Error:

The Problem:

Backslashes in JSON strings must be properly escaped. Common issues include Windows file paths and regex patterns.

{
  "path": "C:\Users\John\Documents",
  "regex": "\d+"
}

The Fix:

Escape backslashes by doubling them:

{
  "path": "C:\\Users\\John\\Documents",
  "regex": "\\d+"
}

Valid Escape Sequences in JSON:

Any other escape sequence (like \d or \s from regex) is invalid in JSON.

6. Unescaped Control Characters

The Error:

The Problem:

Control characters (characters with ASCII codes 0-31) must be escaped in JSON strings. This often happens when copying text that contains tabs or newlines directly into a JSON string.

{
  "message": "Hello
World"
}

That literal newline inside the string breaks JSON parsing.

The Fix:

Use escape sequences for control characters:

{
  "message": "Hello\nWorld"
}

7. Missing Commas Between Elements

The Error:

The Problem:

Forgetting a comma between object properties or array elements.

{
  "name": "John"
  "age": 30
}

The Fix:

Add the missing comma:

{
  "name": "John",
  "age": 30
}

8. Incorrect Boolean or Null Values

The Error:

The Problem:

JSON boolean and null values must be lowercase. JavaScript's True, False, None (from Python), or NULL are not valid.

{
  "active": True,
  "deleted": False,
  "middleName": None
}

The Fix:

Use lowercase true, false, and null:

{
  "active": true,
  "deleted": false,
  "middleName": null
}

9. Numbers with Leading Zeros

The Error:

The Problem:

JSON doesn't allow numbers with leading zeros (except for 0 itself or decimal numbers like 0.5).

{
  "zipCode": 01onal,
  "id": 007
}

The Fix:

Remove leading zeros or convert to strings if the leading zeros are meaningful:

{
  "zipCode": "01onal",
  "id": 7
}

Or if you need to preserve the format:

{
  "zipCode": "01ona",
  "agentId": "007"
}

10. Using undefined

The Error:

The Problem:

undefined is a JavaScript concept that doesn't exist in JSON.

{
  "name": "John",
  "nickname": undefined
}

The Fix:

Use null for missing values, or omit the key entirely:

{
  "name": "John",
  "nickname": null
}

How to Debug JSON Errors Quickly

When you encounter a JSON parsing error, here's a systematic approach to fix it:

Step 1: Use a JSON Validator

Paste your JSON into jsoneditor.io. The editor will immediately highlight syntax errors and show you exactly where the problem is.

Step 2: Check the Error Position

Most JSON parsers tell you the position where parsing failed. Look at that specific location in your JSON. The error is usually at or just before that position.

Step 3: Look for Common Culprits

Check for these issues in order (most common first):

1. Trailing commas
2. Single quotes
3. Missing commas
4. Unquoted keys
5. Comments
6. Invalid escape sequences

Step 4: Validate Programmatically

If you're working with JSON in code, wrap your parsing in a try-catch to get detailed error information:

JavaScript:

try {
  const data = JSON.parse(jsonString);
} catch (error) {
  console.error('JSON Parse Error:', error.message);
  // Error message includes position information
}

Python:

import json

try:
    data = json.loads(json_string)
except json.JSONDecodeError as e:
    print(f"JSON Error at line {e.lineno}, column {e.colno}: {e.msg}")

Preventing JSON Errors

The best way to deal with JSON errors is to prevent them in the first place:

1. Use a JSON-aware editor - Tools like jsoneditor.io validate as you type
2. Generate JSON programmatically - Use JSON.stringify() in JavaScript or json.dumps() in Python instead of building JSON strings manually
3. Use schema validation - Define a JSON Schema to catch structural errors, not just syntax errors
4. Format your JSON - Properly formatted JSON with consistent indentation makes errors easier to spot

FAQ

Why does my JSON work in JavaScript but fail in JSON.parse()?

JavaScript object literals are more forgiving than JSON. They allow unquoted keys, single quotes, trailing commas, and comments. When you call JSON.parse(), you're using the strict JSON specification, which doesn't allow these.

Can I use hexadecimal numbers in JSON?

No. JSON only supports decimal numbers. If you need to store hex values, use strings: "color": "#FF5733".

Why doesn't JSON support comments?

Douglas Crockford, who specified JSON, intentionally excluded comments to keep the format simple and to prevent them from being used as parsing directives. If you need comments, consider using YAML or JSON5.

How do I handle special characters in JSON strings?

Escape them using the valid escape sequences. For characters outside the basic ASCII range, you can use Unicode escapes: "\u00e9" for "e".

Is there a maximum size for JSON files?

The JSON specification doesn't define a maximum size, but practical limits depend on your parser and available memory. Most parsers handle files up to several hundred megabytes without issues.

Summary

JSON syntax errors usually come down to a handful of common mistakes: trailing commas, quote issues, and invalid escape sequences. Once you know what to look for, debugging becomes straightforward.

The fastest way to fix JSON errors is to paste your data into jsoneditor.io. The editor validates your JSON in real-time, highlights errors, and shows you exactly what needs to be fixed. It's free, works entirely in your browser, and doesn't require any signup.

Happy debugging!