10 Most Common JSON Errors and How to Fix Them (With Real-World Examples)

by

If you’ve ever built an API integration, configured a web app, or worked with any modern data pipeline, you’ve encountered JSON. And if you’ve worked with JSON long enough, you’ve run into errors that make you question your career choices.

JSON (JavaScript Object Notation) is deceptively simple. It looks readable, it feels intuitive, and then one missing comma or an accidental trailing space brings an entire application to its knees.

According to the TIOBE Index and developer surveys from Stack Overflow, JSON remains one of the most widely used data interchange formats in software development today.

What Makes JSON So Prone to Errors?

JSON’s strict syntax is both its strength and its weakness. Unlike HTML, which browsers forgive generously, JSON parsers have zero tolerance for mistakes. A single misplaced character will throw an error and halt parsing entirely.

The format follows a small but rigid set of rules:

  • Data is stored in key/value pairs.
  • Keys must be strings wrapped in double quotes.
  • Values can be strings, numbers, booleans, arrays, objects, or null.
  • No comments are allowed.
  • No trailing commas permitted.

That last point alone causes thousands of developer headaches every day.

The 10 Most Common JSON Errors

1. Missing or Mismatched Quotation Marks

The Error:

{ name: "Alice", age: 30 }

Why It Happens: Many developers come from JavaScript backgrounds where unquoted object keys are perfectly valid. In JSON, every key must be a double-quoted string. No exceptions.

The Fix:

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

Pro tip: Single quotes are also invalid in JSON. { 'name': 'Alice' } will fail. Always use double quotes.

2. Trailing Commas

The Error:

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

Why It Happens: Modern JavaScript (ES5+) and Python both allow trailing commas in arrays and objects. Developers copy-paste or auto-format code and carry the habit into JSON files.

The Fix: Remove the comma after the last item:

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

This is one of the most common causes of broken package.json files in Node.js projects — a fact confirmed across thousands of GitHub issues.

3. Undefined or NaN Values

The Error:

{ "score": NaN, "result": undefined }

Why It Happens: Developers serialize JavaScript objects directly to JSON without realizing that NaN, undefined, and Infinity are not valid JSON values. JavaScript’s JSON.stringify() silently drops undefined keys and converts NaN to null.

The Fix: Replace invalid values before serialization:

{ "score": null, "result": null }

Or handle them explicitly in your serialization logic:

const safe = JSON.stringify(obj, (key, value) =>
  typeof value === 'undefined' || Number.isNaN(value) ? null : value
);

4. Comments in JSON

The Error:

{
  // This is the user configuration
  "theme": "dark",
  "language": "en"
}

Why It Happens: JSON was designed without comments by its creator, Douglas Crockford, intentionally so. Yet many configuration files look like they should support comments, leading developers to add them out of habit.

The Fix: Remove all comments. If you need an annotated configuration, switch to JSONC (JSON with Comments), YAML, or TOML, which do support comments. Tools like VS Code support JSONC in .jsonc files and in settings.json.

5. Incorrect Data Types

The Error:

{ "active": "true", "count": "42" }

Why It Happens: When constructing JSON from form inputs or string concatenation, numeric and boolean values often get accidentally wrapped in quotes — turning them into strings.

The Fix:

{ "active": true, "count": 42 }

This is a critical distinction in typed systems and API validation. An API expecting a boolean true will reject a string "true" and return a 400 Bad Request.

6. Missing Commas Between Key-Value Pairs

The Error:

{
  "firstName": "John"
  "lastName": "Doe"
}

Why It Happens: Manual editing, especially in large JSON files, often results in accidentally deleted commas between properties.

The Fix:

{
  "firstName": "John",
  "lastName": "Doe"
}

A linter like ESLint with the jsonc plugin or a dedicated JSON linter will catch this instantly.

7. Unescaped Special Characters in Strings

The Error:

{ "message": "He said "Hello" to her" }

Why It Happens: Special characters like double quotes, backslashes, and control characters must be escaped inside JSON strings. Embedding them raw breaks the parser.

The Fix:

{ "message": "He said \"Hello\" to her" }

Common characters that require escaping:

Character Escaped Form
" \"
\ \\
/ \/
Newline \n
Tab \t
Carriage return \r
Unicode \uXXXX

8. Duplicate Keys

The Error:

{
  "status": "active",
  "status": "inactive"
}

Why It Happens: The JSON specification technically permits duplicate keys, but behavior is undefined — different parsers handle it differently. Some take the first value, some take the last, and some throw an error.

The Fix: Ensure all keys within the same object are unique. This is especially important in large, auto-generated JSON files where merge conflicts can introduce duplicates silently.

Use a tool like JSONLint to detect and flag duplicate keys.

9. Deeply Nested or Circular References

The Error:

const obj = { name: "test" };
obj.self = obj; // Circular reference
JSON.stringify(obj); // Throws: TypeError: Converting circular structure to JSON

Why It Happens: When working with complex objects in JavaScript or Python, circular references (where an object references itself) are common — but JSON cannot represent them.

The Fix: Use a safe serializer:

// Using a replacer to handle circular references
const seen = new WeakSet();
const safe = JSON.stringify(obj, (key, value) => {
  if (typeof value === "object" && value !== null) {
    if (seen.has(value)) return "[Circular]";
    seen.add(value);
  }
  return value;
});

Libraries like flatted or json-stringify-safe handle this elegantly.

10. Encoding Issues (UTF-8 vs. Other Encodings)

The Error:

Unexpected token  in JSON at position 0

Why It Happens: JSON must be encoded in UTF-8 (or UTF-16/UTF-32 with a BOM). Files saved in Latin-1, ISO-8859-1, or Windows-1252 can contain byte sequences that are invalid in UTF-8, causing parsers to fail immediately.

The Fix: Always save JSON files in UTF-8 encoding. In most code editors:

  • VS Code: Click the encoding label in the bottom status bar → “Reopen with Encoding” → UTF-8
  • Notepad++: Encoding menu → Convert to UTF-8

When reading files programmatically in Python:

with open('data.json', encoding='utf-8') as f:
    data = json.load(f)

SON Errors at a Glance

# Error Type Difficulty in Spotting Auto-Fixable? Best Tool to Catch It
1 Missing quotes on keys Medium Sometimes JSONLint, ESLint
2 Trailing commas Easy Yes Prettier, ESLint
3 NaN / undefined values Hard No Custom serializer
4 Comments in JSON Easy Yes VS Code JSONC mode
5 Wrong data types Medium No API schema validators
6 Missing commas Easy Yes JSONLint
7 Unescaped characters Medium Sometimes JSON.stringify()
8 Duplicate keys Hard No JSONLint (advanced)
9 Circular references Hard No flatted, replacer fn
10 Encoding issues Hard Yes Editor re-encode

Real-World Case Studies

Case Study 1: The Broken Deployment Pipeline

A mid-size SaaS startup was using a config.json file to manage environment-specific settings. A developer editing the file manually added a trailing comma after the last database URL entry. The CI/CD pipeline — which reads the config on startup — began throwing cryptic SyntaxError: Unexpected token } errors and failing every deployment for six hours. The team assumed the issue was in their build scripts.

Root cause: One trailing comma. Time lost: Half a business day.

Lesson: Lock your JSON configuration files behind a linter step in CI. One line in a .github/workflows file using jsonlint would have caught this immediately.

Case Study 2: The Silent API Data Loss

A React frontend was sending user preference data to a REST API. The payload included a notifications key set to undefined (the value hadn’t been loaded yet from local state). JavaScript JSON.stringify() silently dropped the undefined key. The backend received incomplete data and overwrote saved preferences with defaults.

Root cause: undefined silently omitted by JSON.stringify(). Impact: Hundreds of users had their preferences reset.

Lesson: Always validate the shape of your data before serialization. Use schemas like Zod or Joi to enforce required fields.

Case Study 3: The Localization File Nightmare

An international e-commerce platform stored UI strings in JSON translation files. A content editor working in Windows added French language strings containing special characters (é, ç, ô) but saved the file in Windows-1252 encoding instead of UTF-8. The Node.js server crashed on startup with a parse error affecting only the French locale — meaning French-speaking customers saw a blank page for two hours during a promotional campaign.

Root cause: File saved in the wrong encoding. Impact: Revenue loss, support tickets.

Lesson: Enforce UTF-8 encoding in your .editorconfig file and add encoding validation to your build process.

Best Tools for Validating JSON

  • JSONLint — The go-to online validator. Paste your JSON and get instant feedback.
  • Prettier — Auto-formats and fixes many common JSON syntax issues.
  • VS Code JSON Language Features — Built-in real-time JSON validation with schema support.
  • ajv (Another JSON Validator) — The fastest JSON Schema validator for Node.js. Validates structure, not just syntax.
  • json_pp — A command-line JSON pretty-printer and validator available on Linux/macOS.

Quick Reference: JSON Validation Workflow

Before committing any JSON file or shipping a payload, run through this checklist:

  1. ✅ All keys are double-quoted strings
  2. ✅ No trailing commas after the last item
  3. ✅ No comments of any kind
  4. ✅ Booleans are true/false, not "true"/"false"
  5. ✅ Numbers are unquoted integers or decimals
  6. ✅ All special characters in strings are escaped
  7. ✅ No NaN, Infinity, or undefined values
  8. ✅ All brackets and braces are matched
  9. ✅ File is saved in UTF-8 encoding
  10. ✅ Run output through JSONLint or your preferred validator

Conclusion

JSON errors are frustrating precisely because the format looks so simple. But that simplicity hides a strict, unforgiving parser underneath. The good news is that every single error type covered in this guide is entirely preventable with the right editor settings, the right linter configuration, and a habit of validating before deploying.

The real-world case studies above aren’t edge cases. They happen in production teams of all sizes, at all skill levels. The difference between teams that recover quickly and teams that lose hours is usually one thing: automated validation baked into the workflow.

If you take one thing away from this guide, let it be this: never let a JSON file reach production without passing through a validator. It takes ten seconds, and it has saved entire release cycles.

Leave a Comment