[DOCS] VS Code docs missing guidance for settings.json parse failures disabling permission rules

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/vs-code

Section/Topic

The Configure settings section for shared ~/.claude/settings.json files, especially the failure mode when a Claude Code settings file cannot be parsed in VS Code.

Current Documentation

The docs currently say:

Claude Code settings in ~/.claude/settings.json: shared between the extension and CLI. Use for allowed commands, environment variables, hooks, and MCP servers. See Settings for details.

Add "$schema": "https://json.schemastore.org/claude-code-settings.json" to your settings.json to get autocomplete and inline validation for all available settings directly in VS Code.

The troubleshooting guide also says:

Run /doctor to diagnose issues. It checks: * Invalid settings files (malformed JSON, incorrect types)

And the permissions guide says:

You can view and manage Claude Code's tool permissions with /permissions. This UI lists all permission rules and the settings.json file they are sourced from.

No page currently explains what happens when a Claude Code settings.json file fails to parse in VS Code.

What's Wrong or Missing?

Changelog v2.1.94 added a VS Code warning banner for settings.json parse failures specifically "so users know their permission rules are not being applied."

The current docs do not explain that a malformed Claude Code settings file can leave permission rules from that file inactive. That is the important user-facing consequence of the parse failure.

The docs also do not mention that VS Code now surfaces this state with a warning banner, or connect the existing prevention and diagnosis tools ($schema, /doctor, and /permissions) into a clear recovery path for this failure mode.

Suggested Improvement

Add a short warning note to the VS Code settings section, with supporting clarification in Settings or Troubleshooting, covering:

• If ~/.claude/settings.json or .claude/settings.json fails to parse, Claude Code cannot apply permission rules from that file
• VS Code shows a warning banner when this happens
• Users should fix the JSON or schema validation errors, then verify their active rules with /doctor and /permissions
• The existing $schema recommendation is the best way to catch these errors earlier inside VS Code

A small subsection such as If settings.json fails to parse would make this easy to discover.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/vs-code | Shared settings.json setup for VS Code extension users |
| https://code.claude.com/docs/en/settings | JSON schema and validation guidance for Claude Code settings |
| https://code.claude.com/docs/en/permissions | Explains that permission rules are loaded from settings files and surfaced in /permissions |
| https://code.claude.com/docs/en/troubleshooting | /doctor diagnostics for invalid settings files |

Total scope: 4 pages affected

Source: Changelog v2.1.94

Exact changelog entry: [VSCode] Added a warning banner when settings.json files fail to parse, so users know their permission rules are not being applied