Fix Claude Code Config YAML Parse Error

The Error

Error: Failed to parse configuration file
YAMLException: bad indentation of a mapping entry (2:3)
  at /Users/you/.claude/settings.json

# Or for CLAUDE.md YAML frontmatter:
Error: Invalid YAML frontmatter in CLAUDE.md
  expected a single document in the stream
  but found another document at line 5, column 1

# Or:
SyntaxError: Unexpected token ':' in JSON at position 42
  Could not parse settings.json

The Fix

1. Validate your config file syntax

# For JSON config (settings.json):
python3 -c "import json; json.load(open('$HOME/.claude/settings.json')); print('JSON valid')"

# For YAML frontmatter in CLAUDE.md:
python3 -c "
import yaml
with open('CLAUDE.md') as f:
    content = f.read()
    if content.startswith('---'):
        end = content.index('---', 3)
        yaml.safe_load(content[3:end])
        print('YAML frontmatter valid')
"

2. Fix common syntax mistakes

The settings.json file must be valid JSON with no trailing commas:

{
  "permissions": {
    "allow": ["Bash", "Read", "Write"],
    "deny": []
  }
}

3. Verify the fix

python3 -c "import json; json.load(open('$HOME/.claude/settings.json')); print('Config OK')" && claude --version

Why This Happens

Claude Code reads configuration from ~/.claude/settings.json (JSON format) and project-level CLAUDE.md files (which may contain YAML frontmatter). JSON is strict about syntax -- trailing commas, unquoted keys, and single quotes are all parse errors. YAML frontmatter requires proper indentation (spaces only, no tabs) and must be enclosed between --- delimiters. Editors that auto-insert smart quotes or tabs break both formats silently.

If That Does Not Work

• Delete and recreate the config: mv ~/.claude/settings.json ~/.claude/settings.json.bak && claude -- Claude Code creates a fresh default config
• Use an online JSON/YAML validator like jsonlint.com to pinpoint the exact character
• Reveal hidden characters: Run cat -A ~/.claude/settings.json to see tabs (shown as ^I) and carriage returns (shown as ^M)

Common JSON Mistakes

// WRONG: trailing comma
{ "key": "value", }

// WRONG: single quotes
{ 'key': 'value' }

// WRONG: unquoted keys
{ key: "value" }

// WRONG: comments in JSON
{ "key": "value" /* comment */ }

// CORRECT
{ "key": "value" }

Prevention

Use spaces not tabs in all config files. Validate JSON with python3 -c "import json; json.load(open('file'))" after editing. Never use trailing commas in JSON config files. Use a proper code editor with JSON syntax highlighting to catch errors immediately.