Common Bugs & Debugging Tooling

The five bugs you will hit, and how to fix them fast

1. Trailing comma

The single most common JSON parse error. {"a": 1,} dies with 'expected property name, got }'. Fix: remove the trailing comma. Prevention: format on save with a tool that knows JSON's rules.

2. Single quotes

Pasted from JS / Python source: {'name': 'Pippa'}. The fix is mechanical: sed "s/'/\"/g", or paste through JSON.stringify(eval(...)) in a sandbox, or just retype.

3. Comments

// comment or /* ... */ in JSON dies. The fix: strip them, or switch to JSONC (VS Code config) / JSON5 (with explicit parser opt-in). Don't fight the spec.

4. Unescaped special characters in strings

Raw newlines, raw tabs, lone backslashes inside strings. Use \n, \t, \\. The error usually points one line later than the actual mistake.

5. Encoding mismatch

UTF-8 with a BOM (byte order mark) at the start trips strict parsers. Many editors add the BOM silently on Windows. Fix: save as 'UTF-8 without BOM'. The error message is usually 'unexpected token at position 0'.

The 30-second debug loop: when a JSON file won't parse, run jq . file.json. jq tells you the line and column of the syntax error in a way most language stdlibs don't. For deeply nested issues, jq -e exits non-zero on parse failure — useful in CI.

Code

Validate from the shell·bash

# Quick yes/no validation:
jq -e . config.json > /dev/null && echo OK || echo BROKEN

# Python equivalent:
python -m json.tool config.json > /dev/null && echo OK || echo BROKEN

# Node equivalent:
node -e 'JSON.parse(require("fs").readFileSync("config.json"))' && echo OK || echo BROKEN

Pretty error reporting from Python·python

import json

try:
    with open('config.json') as f:
        data = json.load(f)
except json.JSONDecodeError as e:
    print(f'JSON error at line {e.lineno}, column {e.colno}: {e.msg}')
    # Read the file once, show the offending line:
    with open('config.json') as f:
        lines = f.readlines()
    print(f'  >>> {lines[e.lineno - 1].rstrip()}')
    print(f'      {" " * (e.colno - 1)}^')

jq for inspection (a few moves)·bash

# Show all keys at the top level
jq 'keys' data.json

# Show all values for one key, across an array
jq '.[].name' users.json

# Filter to an object
jq '.[] | select(.age > 18)' users.json

# Type of every top-level value
jq 'to_entries | map({key, type: (.value | type)})' data.json

Exercise

Find a JSON file on your machine that you didn't write yourself (a vendored config, an exported dataset, a downloaded API response). Run jq . file.json and python -m json.tool file.json. Then deliberately introduce each of the five bugs above one at a time and read the error each tool emits. Memorize the smell of each error message — it's how you'll fix the next one in 30 seconds instead of 10 minutes.

Common Bugs & Debugging Tooling

The five bugs you will hit, and how to fix them fast

1. Trailing comma

2. Single quotes

3. Comments

4. Unescaped special characters in strings

5. Encoding mismatch

Code

External links

Exercise

Progress

Comments 0