[DOCS] Startup recovery dialog behavior for corrupted config files is undocumented

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/settings

Section/Topic

The "Configuration files" / "Settings files (JSON)" section under "Key points about the configuration system", and the existing backup <Note> near the ~/.claude.json description. A new section documenting the corrupted-config recovery flow is also missing from the Troubleshooting page (no entry covers the case where startup fails because of a corrupted settings or ~/.claude.json file).

Current Documentation

The settings page currently states only:

Other configuration is stored in ~/.claude.json. This file contains your OAuth session, MCP server configurations for user and local scopes, per-project state (allowed tools, trust settings), and various caches. Project-scoped MCP servers are stored separately in .mcp.json. Claude Code automatically creates timestamped backups of configuration files and retains the five most recent backups to prevent data loss.

And in the managed-settings validation section:

Interactive sessions show a dialog at startup listing the invalid entries.

The Troubleshooting page does not describe the corrupted-config startup recovery flow at all. There is no section on "corrupted config file", "startup recovery dialog", "config reset", or what happens when the user accepts a reset from the dialog.

What's Wrong or Missing?

A. The startup recovery dialog itself is undocumented

When Claude Code detects a corrupted config file (settings.json or ~/.claude.json) at startup, it shows a recovery dialog offering to reset. Before v2.1.199, accepting the reset destroyed the original file with no copy, leaving users without their OAuth session, allowedTools list, per-project state, or custom MCP servers. v2.1.199 backs the file up first so the reset is recoverable. None of this flow is documented anywhere on the docs site — there is no mention of the dialog, no mention of the "reset" action it offers, and no mention that the reset now creates a recoverable backup.

B. The auto-backup Note understates scope and lacks the new recovery behavior

The current Note says backups are created "automatically" and retained as the "five most recent", but it does not:

• Identify which paths get backed up (~/.claude/settings.json, ~/.claude.json, project .claude/settings.json, etc.).
• Document that the startup recovery dialog now uses this backup mechanism when a user accepts a reset on a corrupted file.
• Note where the timestamped backup files live (~/.claude/backups/, per the changelog entry moving backups out of $HOME in an earlier release).
• Explain how a user can manually recover from one of these backups if a future corruption is not caught by the dialog.

C. The Troubleshooting page has no entry for corrupted config files

The Troubleshooting page routes "Settings not applying, hooks not firing, MCP servers not loading" to Debug your configuration, but there is no entry for the case where Claude Code refuses to start at all because of a corrupted config file, and no pointer to the recovery dialog or the backup location. Users hitting this error currently have no documented path forward.

Suggested Improvement

Option A: Add a new section to the Settings page documenting the recovery flow

Add after the existing auto-backup Note near the ~/.claude.json description:

### Recovering from a corrupted config file If Claude Code finds a settings file or ~/.claude.json it cannot parse, it shows a startup recovery dialog describing the corruption and offering a reset. From v2.1.199, accepting the reset first copies the original file to a timestamped entry under ~/.claude/backups/ before replacing it, so the previous OAuth session, MCP servers, and allowed-tools list can be restored manually if the reset loses something you still need. To restore from a backup, copy the desired timestamped file back to its original location (~/.claude/settings.json, ~/.claude.json, or .claude/settings.json for project scope) and start Claude Code again. Claude Code retains the five most recent timestamped backups and prunes older ones.

Option B: Add a Troubleshooting entry and cross-reference the Settings page

Add to the Troubleshooting page a new "Claude Code refuses to start because of a corrupted config file" entry in the symptom table at the top, pointing to a short subsection that explains the startup recovery dialog, the backup-first behavior in v2.1.199, and the manual restore steps. Cross-reference the Settings page section added in Option A.

Either option closes the documentation gap. Option A is the minimum fix; Option B gives the issue a discoverable entry point from the Troubleshooting symptom table.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/settings | ~122 | Existing auto-backup Note that should call out the dialog flow and backup location |
| https://code.claude.com/docs/en/settings | ~188 | "Interactive sessions show a dialog at startup" describes the managed-settings validation dialog, not the corrupted-config recovery dialog — readers can confuse the two |
| https://code.claude.com/docs/en/troubleshooting | 11–20 | Symptom table has no row for "Claude Code refuses to start because of a corrupted config file" |
| https://code.claude.com/docs/en/debug-your-config | 40–46 | Covers invalid key/schema validation via /doctor, but does not cover corrupted-file recovery or the startup dialog |

Total scope: 4 pages affected.

Version: Claude Code v2.1.199 (changelog entry: "Fixed resetting a corrupted config file from the startup recovery dialog destroying it unrecoverably — it now backs up the file first"). The dialog itself pre-dates v2.1.199; v2.1.199 changes only the backup-before-reset behavior, but neither the dialog nor the backup behavior has ever been documented on the site.

Cross-reference: The changelog previously moved config backup files from $HOME to ~/.claude/backups/ (changelog entry near line 2973) and reduced on-startup backup accumulation (entries near lines 3000 and 3359). The current Note in the Settings page does not reflect either of these storage-location changes; documenting the recovery flow would also let that Note reflect the actual ~/.claude/backups/ location.