Root Cause Analysis of Common JSON Processing Errors

Start With the Failure Stage

1. Check the raw input first: HTTP status, `Content-Type`, response body, or file bytes before any parsing.
2. Classify the failure: decode problem, syntax problem, shape/type problem, or business-rule problem.
3. Reduce the payload to the smallest example that still fails.
4. Compare the failing payload to the contract you actually consume, not the one you assume.
5. Fix the producer when possible; defensive consumer code should be a safety net, not the only fix.

Common Invalid Patterns

{
  "name": "Alice",
  "age": 30, // invalid in JSON
}

{
  name: 'Alice'
}

{
  "value": undefined,
  "other": NaN
}

Root Causes

• A JSON file was edited like JavaScript, JSON5, or JSONC.
• Code built JSON through string concatenation instead of real serialization.
• User input was injected without proper escaping.
• A tool exported a relaxed format, but the consumer expected strict JSON.

What Fixes It

• Serialize objects with a real library instead of hand-building strings.
• Validate the exact raw payload, not the object you expected to produce.
• Convert JSON5/JSONC-style configs before passing them to strict parsers.

High-Probability Causes

• The request hit the wrong route or environment.
• An auth gateway returned a sign-in page or `401`/`403` HTML body.
• A reverse proxy, CDN, or framework rendered an error document.
• The server returned text like `OK`, but the client always assumed JSON.

const response = await fetch(url);
const contentType = response.headers.get("content-type") ?? "";

if (response.status === 204) {
  return null;
}

const raw = await response.text();

if (!contentType.includes("application/json")) {
  throw new Error(
    `Expected JSON but received ${contentType || "unknown content type"}: ${raw.slice(0, 200)}`,
  );
}

const data = JSON.parse(raw);

Checking status, headers, and the first part of the raw body usually resolves this class of problem faster than staring at the parser message.

What Usually Went Wrong

• The response legitimately had no body, such as `204 No Content` or `HEAD`.
• A file read returned zero bytes or partial bytes.
• A network hop cut the response short before the closing brace or bracket arrived.
• The server declared compression incorrectly, so decoding failed before parsing.
• The response body was already consumed by another reader before `response.json()` ran.

Fast Checks

• Log body length before parsing.
• Handle empty-response status codes explicitly.
• Store the raw body once during debugging so you can inspect exactly what arrived.
• Verify compression and transfer settings at the server or proxy layer.

Common Drift Patterns

• A required field was removed or renamed.
• A scalar became an object, or an object became an array.
• A value changed from number to string, often for IDs or timestamps.
• `null` started appearing where the consumer assumed non-null data.
• The payload was wrapped in `data`, `result`, or another top-level envelope.

type User = {
  id: string;
  email: string;
  displayName?: string | null;
};

function parseUser(input: unknown): User {
  if (!input || typeof input !== "object") {
    throw new Error("Expected an object");
  }

  const user = input as Record<string, unknown>;

  if (typeof user.id !== "string" || typeof user.email !== "string") {
    throw new Error("Invalid user payload");
  }

  if (user.displayName != null && typeof user.displayName !== "string") {
    throw new Error("displayName must be string, null, or omitted");
  }

  return {
    id: user.id,
    email: user.email,
    displayName: (user.displayName as string | null | undefined) ?? null,
  };
}

Runtime validation is what turns a vague downstream crash into an actionable contract error close to the boundary.

Duplicate Keys

{
  "id": 1,
  "id": 2
}

Different parsers handle duplicate names differently. Many keep only the last value, which means the input may parse without an obvious error while silently discarding data.

Large Numbers and Precision Loss

{
  "invoiceId": 9223372036854775807
}

That value is valid JSON, but many JavaScript environments cannot represent every integer beyond the safe range exactly. If an ID, money amount, or hash-like value must be preserved exactly, send it as a string or use a lossless parsing strategy.

Encoding Problems

JSON exchanged across open systems should be UTF-8. Mis-encoded files, invalid Unicode, or byte-order-mark edge cases can surface as replacement characters, decode failures, or inconsistent parser behavior.