Fix JSON Errors: The Complete Developer Guide

// Inside a JSON string, these characters must be escaped:
{
  "path": "C:\\Users\\Alice\\Documents",   // \ → \\
  "quote": "She said \"hello\"",               // " → \"
  "newline": "line1\nline2",                    // newline → \n
  "tab": "col1\tcol2",                          // tab → \t
  "emoji": "Works fine: \u2764",                // Unicode OK
  "null_byte": "NOT OK in plain strings"         // \u0000 needs escape
}

// ✅ Use JSON.stringify to generate valid JSON from JS values:
const obj = { message: 'She said "hello"', path: 'C:\Users\Alice' };
const safe = JSON.stringify(obj);
// '{"message":"She said \"hello\"","path":"C:\\Users\\Alice"}'

async function fetchJSONSafe<T>(url: string, options?: RequestInit): Promise<T> {
  let res: Response;
  try {
    res = await fetch(url, options);
  } catch (networkError) {
    // DNS failure, timeout, connection refused
    throw new Error(`Network error: ${(networkError as Error).message}`);
  }

  // Handle 204 No Content
  if (res.status === 204) return undefined as T;

  const text = await res.text();

  // Guard against empty body
  if (!text || text.trim() === '') {
    if (!res.ok) throw new Error(`HTTP ${res.status} with empty body`);
    return undefined as T;
  }

  // Check Content-Type
  const ct = res.headers.get('content-type') ?? '';
  if (!ct.includes('application/json') && !ct.includes('text/json')) {
    throw new Error(
      `Expected JSON, got "${ct}". First 200 chars: ${text.slice(0, 200)}`
    );
  }

  let data: T;
  try {
    data = JSON.parse(text);
  } catch (parseError) {
    throw new Error(
      `JSON parse failed: ${(parseError as Error).message}. ` +
      `Raw (first 500 chars): ${text.slice(0, 500)}`
    );
  }

  if (!res.ok) {
    const errMsg = (data as any)?.message ?? (data as any)?.error ?? JSON.stringify(data);
    throw new Error(`HTTP ${res.status}: ${errMsg}`);
  }

  return data;
}

// ❌ This throws TypeError
const obj: any = { name: 'Alice' };
obj.self = obj;  // circular reference!
JSON.stringify(obj); // TypeError: Converting circular structure to JSON

// ✅ Option 1: Use a WeakSet to detect cycles
function safeStringify(obj: unknown, indent?: number): string {
  const seen = new WeakSet();
  return JSON.stringify(obj, (_key, value) => {
    if (typeof value === 'object' && value !== null) {
      if (seen.has(value)) return '[Circular]';
      seen.add(value);
    }
    return value;
  }, indent);
}

// ✅ Option 2: Use the 'flatted' or 'json-stringify-safe' npm package
import stringify from 'json-stringify-safe';
const safe = stringify(circularObj, null, 2);

// ✅ Option 3: For logging, use util.inspect (Node.js)
import util from 'util';
console.log(util.inspect(circularObj, { depth: 4, circular: true }));

// ── 1. Safe parse with fallback ──────────────────────────────
export function parseJSON<T>(raw: string, fallback: T): T {
  try {
    return JSON.parse(raw) as T;
  } catch {
    return fallback;
  }
}

// ── 2. Safe parse that returns Result type ────────────────────
type ParseResult<T> =
  | { ok: true; data: T }
  | { ok: false; error: string; raw: string };

export function parseJSONResult<T>(raw: string): ParseResult<T> {
  try {
    return { ok: true, data: JSON.parse(raw) as T };
  } catch (e) {
    return {
      ok: false,
      error: (e as SyntaxError).message,
      raw: raw.slice(0, 200),
    };
  }
}

// Usage:
const result = parseJSONResult<User>(apiResponse);
if (!result.ok) {
  console.error('Parse failed:', result.error, 'Raw:', result.raw);
  showErrorToUser('Failed to load data. Please refresh.');
} else {
  setUser(result.data);
}

// ── 3. localStorage safe helpers ─────────────────────────────
export function getLocalStorageJSON<T>(key: string, fallback: T): T {
  try {
    const raw = localStorage.getItem(key);
    if (raw === null) return fallback;
    return JSON.parse(raw) as T;
  } catch {
    // localStorage had corrupted data — clear and return fallback
    localStorage.removeItem(key);
    return fallback;
  }
}

export function setLocalStorageJSON(key: string, value: unknown): boolean {
  try {
    localStorage.setItem(key, JSON.stringify(value));
    return true;
  } catch {
    // Quota exceeded or value is not serializable
    return false;
  }
}

import { useState, useEffect } from 'react';

interface ApiResponse<T> {
  data: T | null;
  loading: boolean;
  error: string | null;
}

export function useAPI<T>(url: string): ApiResponse<T> {
  const [state, setState] = useState<ApiResponse<T>>({
    data: null,
    loading: true,
    error: null,
  });

  useEffect(() => {
    let cancelled = false;

    async function load() {
      setState(s => ({ ...s, loading: true, error: null }));
      try {
        const res = await fetch(url);

        // Check content type before parsing
        const ct = res.headers.get('content-type') ?? '';
        if (!ct.includes('application/json')) {
          const text = await res.text();
          throw new Error(
            `Server returned non-JSON (${ct}). ` +
            `Status: ${res.status}. Body: ${text.slice(0, 100)}`
          );
        }

        const data: T = await res.json();

        if (!cancelled) {
          setState({ data, loading: false, error: null });
        }
      } catch (e) {
        if (!cancelled) {
          setState({ data: null, loading: false, error: (e as Error).message });
        }
      }
    }

    load();
    return () => { cancelled = true; };
  }, [url]);

  return state;
}

// Component usage
function UserProfile({ userId }: { userId: string }) {
  const { data: user, loading, error } = useAPI<User>(`/api/users/${userId}`);

  if (loading) return <Spinner />;
  if (error) return <ErrorBanner message={error} />;
  return <div>{user?.name}</div>;
}

import express from 'express';
import { z } from 'zod'; // zod for schema validation

const app = express();
app.use(express.json({
  // Handle JSON parse errors at the middleware level
  strict: true,
  limit: '1mb',
}));

// Handle JSON parse errors from express.json() middleware
app.use((err: any, req: express.Request, res: express.Response, next: express.NextFunction) => {
  if (err.type === 'entity.parse.failed') {
    return res.status(400).json({
      error: 'Invalid JSON in request body',
      detail: err.message,
    });
  }
  next(err);
});

// Define schema with zod
const CreateUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
  age: z.number().int().min(0).max(150),
});

app.post('/api/users', (req, res) => {
  const result = CreateUserSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(422).json({
      error: 'Validation failed',
      details: result.error.format(),
    });
  }
  const { name, email, age } = result.data;
  // ... create user
  res.status(201).json({ id: 'new-id', name, email, age });
});

# Validate a JSON file with jq
jq . config.json

# Pretty-print a JSON file
jq . raw.json | less

# Query nested data
curl -s https://api.example.com/users | jq '.data[0].name'

# Check if an API returns JSON (curl)
curl -I https://api.example.com/users
# Look for: Content-Type: application/json

# Validate JSON string in Node.js
node -e "JSON.parse(require('fs').readFileSync('data.json', 'utf8')); console.log('Valid!')"

# Fix common JSON issues with python
python3 -c "import json,sys; json.dump(json.load(sys.stdin), sys.stdout, indent=2)"

# Install jsonlint globally for nicer errors
npm i -g jsonlint
jsonlint config.json