When a Broken settings.json Stops Claude Code From Starting — Safe Mode and How to Split Your Config

Recovering a broken file safely

Once you know the culprit, don't edit blindly — first build a footing you can roll back to. Settings files aren't always under version control, so I always take a timestamped backup before touching anything.

# Stash the broken file before editing (prevents overwrite accidents)
BROKEN="$HOME/.claude/settings.json"
cp "$BROKEN" "${BROKEN}.broken.$(date +%Y%m%d-%H%M%S)"
 
# Mechanically check the "usual ways people break it"
grep -nE ',\s*[}\]]' "$BROKEN" && echo "^ possible trailing comma"
grep -nE '^\s*//' "$BROKEN" && echo "^ JSON does not allow comments"

In my experience, the vast majority of broken configs come down to three causes: a trailing comma, a comment written into JSON, and an unclosed string quote. The grep above flushes out those top three at once. After fixing, run jq empty again before relaunching, and only restart Claude Code once it's green.

When you truly can't trace the cause, the approach I personally find most reliable is to binary-search it back in, step by step:

1. Swap the broken file for {} (an empty valid JSON object) and confirm startup passes with no config. If it does, the problem is in the content.
2. Restore only the permissions block from your backup, re-validate with jq empty, and relaunch.
3. Restore the env block, then hooks, one at a time, to find exactly which block breaks it again.

# Swap in a minimal valid settings to test whether startup passes
echo '{}' > "$HOME/.claude/settings.json"
# If startup passes now, the problem is somewhere in the content.
# Restore from the stash block by block.

{} (an empty object) is perfectly valid config, so if startup passes the problem is definitely in the content. Safe mode is only first aid: while a file stays quarantined, its permissions.deny isn't enforced, which is a dangerous state — so I'd strongly recommend not relaxing just because it booted. Restore to a fully valid config.

Splitting your config so it doesn't break in the first place

This is the part that matters more than recovery. If you cram permissions, environment variables, and hooks into one giant settings.json, a single mistake invalidates the whole file and drags unrelated settings down with it. After getting burned in my four-site automation, I restructured my config so that breakage stays local. Because I run app updates for the App Store and Google Play and article generation from the same machine, a config accident left unattended spreads across several systems at once.

The idea is simple: split by change frequency and risk. The rarely-touched permission foundation goes in the project-shared .claude/settings.json, while frequently-edited experimental settings and personal overrides are isolated in .claude/settings.local.json. That way, if you break local settings mid-experiment, the shared permissions.deny — your safety net — survives.

// .claude/settings.json — the rarely-changed "safety foundation"
{
  "permissions": {
    "deny": [
      "Bash(rm -rf /*)",
      "Bash(git push --force:*)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

// .claude/settings.local.json — the frequently-edited "experiment zone"
{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(jq:*)"
    ]
  },
  "env": {
    "MY_FEATURE_FLAG": "1"
  }
}

The benefit of this split is that the rules you most want to protect — denying destructive commands and secret-file reads — ride on the file least likely to break. Breaking an experimental allow in settings.local.json leaves the safety foundation untouched. Conversely, writing deny into the experiment file is a mistake: I'd recommend keeping the safety net in the most stable file. (For pinning the model against unintended auto-upgrades, I cover that separately in Pinning your run model with enforceAvailableModels.)

The "I fixed it but nothing changed" case on team-managed Macs

You rarely hit this in solo use, but on a team-provisioned Mac there's an extra layer of subtlety. The enterprise managed policy (managed-settings.json) loads at the top priority, so if it defines permissions.deny, no amount of allow you add in ~/.claude/settings.json will override it. When "I fixed my own settings but the behavior didn't change," the shortcut is to check for a managed policy first.

# Check whether a managed policy exists and what it enforces, first
MGD="/Library/Application Support/ClaudeCode/managed-settings.json"
if [ -f "$MGD" ]; then
  echo "Managed policy present: $MGD"
  jq '.permissions // {}' "$MGD"   # show what's being enforced
else
  echo "No managed policy — user/project settings are in effect"
fi

A managed policy is enforced on purpose, so you shouldn't quietly rewrite it. Operations it denies are meant to be honored as an organizational rule, and I'd rebuild the rest of my config around that assumption. Put differently, checking this one file before you suspect your own settings.json can cut a lot of triage time.

In automation, make "validate before you write" a mechanism

Being careful by hand won't prevent accidents that happen inside an automated pipeline. My scheduled runs include steps that rewrite settings with sed or cat, so I always route them through a gate that stops the moment a written JSON is broken — catching it right after the file is updated, not at push time.

# After rewriting settings, validate immediately and roll back if broken
write_settings() {
  local target="$1" tmp
  tmp="$(mktemp)"
  cat > "$tmp"                      # receive new content from stdin
  if jq empty "$tmp" 2>/dev/null; then
    cp "$target" "${target}.prev"   # stash the last valid version
    mv "$tmp" "$target"
    echo "✅ settings updated (validated): $target"
  else
    echo "🛑 invalid JSON, write aborted: $target"
    jq empty "$tmp"                 # show error location
    rm -f "$tmp"
    return 1
  fi
}
 
# Usage: pass new settings via stdin
cat << 'JSON' | write_settings "$HOME/.claude/settings.json"
{ "permissions": { "deny": ["Bash(rm -rf /*)"] } }
JSON

This function writes to a temp file, validates with jq empty, and only mvs to the live file when it passes. On failure it never touches the live file and keeps the last valid version (.prev), so broken content never reaches production. Once I made "validate, then replace" a mechanism, the config-induced stalls that used to hit me a couple of times a month dropped to nearly 0%. This isn't specific to settings files either — it mirrors the design principle across my whole pipeline, where generated articles pass a quality gate before they're pushed. It all comes down to one thing: anything that might be broken gets rejected before it reaches production.

If I'd recommend one practice, it's this: run your current ~/.claude/settings.json through jq empty once. Even if it's working fine today, confirming its validity now makes the next config change feel completely different. I hope this helps anyone else handling settings inside an automated workflow.