Feature Request: Enhance `/doctor` to show specific JSON parsing errors in settings files

[coygeek]

Title: Feature Request: Enhance /doctor to show specific JSON parsing errors in settings files

Is your feature request related to a problem? Please describe.

Currently, when a settings.json file is malformed (e.g., contains a syntax error like a missing comma), the /doctor command provides a generic error message.

 Invalid Settings
 /Users/user/.claude/settings.json
  └ Invalid or malformed JSON

While it's helpful that /doctor identifies the problematic file, the "Invalid or malformed JSON" message isn't specific enough to help the user quickly locate and fix the error. The user has to manually inspect the entire file or paste it into an external validator to find the syntax issue, which can be time-consuming, especially for larger configuration files.

Describe the solution you'd like

I propose enhancing the /doctor command to include more specific details about the JSON parsing error. When an invalid settings.json file is detected, the output should not only identify the file but also provide context about the error itself.

Ideally, this would include:

• The line and column number where the syntax error occurs.
• A brief, high-level description of the error (e.g., "Unexpected token", "Missing comma").

This would make the /doctor command a much more powerful and useful diagnostic tool for configuration issues.

Describe alternatives you've considered

The current alternative is to copy the contents of the settings file and paste it into an online JSON validator or an IDE, which is an extra, inconvenient step. Integrating this basic validation feedback directly into /doctor would create a much smoother user experience.

Example of Desired Behavior

Here is a mock-up of how the improved output could look:

 Invalid Settings
 /Users/user/.claude/settings.json
  └ Invalid or malformed JSON: Unexpected token "}" at line 42, column 5

Or, for a different type of error:

 Invalid Settings
 /Users/user/.claude/settings.json
  └ Invalid or malformed JSON: Missing comma after key-value pair at line 18, column 12

Additional context

This feature would align with the "doctor" metaphor by not just diagnosing a problem ("you have a broken file") but also providing a more precise location of the issue ("the break is here"), empowering users to fix their own configuration problems quickly and efficiently.

Thank you for considering this enhancement

[github-actions[bot]]

Found 1 possible duplicate issue:

1. https://github.com/anthropics/claude-code/issues/2835

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[marcotama]

It is still active, of course! I just ran into this and don't understand what is wrong with my settings.json:

{
  "permissions": {
    "allow": [
      "Bash(./gradlew compileKotlin:*)",
      "WebFetch(domain:docs.spring.io)",
      "Bash(./gradlew :backend:test)",
      "Bash(pnpm test:unit:*)"
    ],
    "deny": [
      "Read(**/.env)",
      "Read(**/secrets.properties)",
      "Read(**/variables.properties)"
    ]
  },
  "instructions": "DO NOT TAKE INITIATIVES. Only perform the exact actions explicitly requested by the user. Do not make changes, edits, or updates unless directly asked."
}

[coygeek]

@marcotama

The primary issue with your settings.json is the use of an unsupported top-level key. Based on the documentation, here is a breakdown of what is wrong and how to fix it:

1. Unsupported instructions key

There is no instructions field in the Claude Code settings.json schema. If you want to provide custom instructions like "DO NOT TAKE INITIATIVES," you have two options:

• Recommended: Put these instructions in a CLAUDE.md file in your project root. This is the standard way to manage project-specific behavior and memory.
• Alternative: Use the systemPrompt key in settings.json with the append property (available in newer versions), or use the --append-system-prompt CLI flag.

2. Permissions Syntax Check

While your permissions are syntactically correct, here are two subtle points to watch out for:

• Read Globs: You used Read(**/.env). While Claude uses gitignore style matching, the documentation recommends being explicit about the path relative to the settings file. If this is a project-level config, Read(/**/.env) or Read(/.env) is often more reliable to ensure it catches files relative to the project root.
• Bash Wildcards: Your use of :* (e.g., pnpm test:unit:*) is correct. Remember that this is a prefix match only. It will not match if the user/Claude puts an environment variable before the command (e.g., NODE_ENV=test pnpm test:unit:auth).

---

Corrected settings.json

If you want to keep everything in one file, use the systemPrompt structure (Note: this appends your text to the internal system prompt):

{
  "permissions": {
    "allow": [
      "Bash(./gradlew compileKotlin:*)",
      "WebFetch(domain:docs.spring.io)",
      "Bash(./gradlew :backend:test)",
      "Bash(pnpm test:unit:*)"
    ],
    "deny": [
      "Read(/**/.env)",
      "Read(/**/secrets.properties)",
      "Read(/**/variables.properties)"
    ]
  },
  "systemPrompt": {
    "type": "preset",
    "preset": "claude_code",
    "append": "DO NOT TAKE INITIATIVES. Only perform the exact actions explicitly requested by the user. Do not make changes, edits, or updates unless directly asked."
  }
}

Better Alternative: Use CLAUDE.md

Remove the instructions from the JSON and create a file named CLAUDE.md in your project root:

# Instructions
- DO NOT TAKE INITIATIVES. 
- Only perform the exact actions explicitly requested by the user. 
- Do not make changes, edits, or updates unless directly asked.

Claude Code automatically reads this file at startup and is much more likely to adhere to instructions formatted this way.