Diagnose ignored settings
Walk through scope conflicts, invalid JSON, precedence rules, and environment overrides — or run the browser-only diagnostic.
Most "settings.json not working" problems are one of four things: wrong file location, invalid JSON, a higher-precedence source overriding a scalar value, or a launch setting that changes which configuration is loaded.
~/.claude.json instead of ~/.claude/settings.json, or placed the project file in the wrong directory.Managed > command line > Local > Project > User. Array settings such as permission rules are merged across scopes and deduplicated.CLAUDE_CONFIG_DIR relocates the user configuration root. --settings overrides the keys it provides, and --setting-sources can exclude normal settings scopes.Before changing anything, run /status. It shows the active settings layers and affected files, but it does not identify the source of every individual key.
Claude Code reads settings from specific paths. A file elsewhere is not loaded as a normal settings source.
~/.claude/settings.json%USERPROFILE%\.claude\settings.json<project-root>/.claude/settings.json<project-root>/.claude/settings.local.jsonThe most common mistake is editing ~/.claude.json instead of ~/.claude/settings.json. The first file stores application state, not user settings. If CLAUDE_CONFIG_DIR is set, Claude Code uses that directory in place of ~/.claude for user configuration, credentials, and related data.
Common JSON mistakes
{
"permissions": {
"allow": [
"Bash(npm run test *)"
],
"deny": [
Read(./.env) ← missing quotes around the string
]
}
}Current Claude Code versions display a Settings Error at startup when a settings file is invalid. If you continue, /status lists the affected file. The terminal command claude doctor provides read-only diagnostic details, and /doctor inside a session also checks the configuration.
You can validate syntax externally with python3 -m json.tool ~/.claude/settings.json. The published JSON schema at json.schemastore.org/claude-code-settings.json provides editor autocomplete and inline validation when referenced with "$schema".
Even when your file is valid and in the right location, a higher-precedence source can override scalar values in it.
Managed > command line > Local > Project > UserFor scalar values such as single strings, booleans, and numbers, the highest-precedence source that sets a key wins. Your user file can be valid and still lose to a project, local, command-line, or managed value.
If your user file allows Read and the project file allows Bash(npm run *), the permission arrays are concatenated and deduplicated. Both rules can take effect; the project array does not replace the user array wholesale.
--settings <file-or-json> supplies settings at command-line precedence, but only its explicit keys override lower scopes. --setting-sources can limit which user, project, and local settings sources Claude Code loads.
Run /status to inspect the active settings layers and any files with errors. It can confirm whether a layer is active, but it does not show a source for each individual key.
Environment variables and launch differences can change where Claude Code looks or which settings sources it loads.
If this environment variable is set, Claude Code uses that directory in place of ~/.claude for user configuration. Run echo $CLAUDE_CONFIG_DIR (or echo %CLAUDE_CONFIG_DIR% in Windows Command Prompt) to check.
An IDE extension or launcher may pass --settings with a file or inline JSON, or use --setting-sources to limit loaded scopes. Check the extension or launcher configuration.
Project-scoped files live under the project Claude Code opens. An IDE may open a different project root than the directory used by your terminal session.
The CLI, VS Code, and JetBrains use the same settings system, but the inherited environment and launch arguments can differ. If the problem appears only in one surface, compare those inputs.
Quick checklist
Work through these in order to separate a load failure from a precedence or launch-context problem.
User: ~/.claude/settings.json. Project: .claude/settings.json. Local: .claude/settings.local.json. Other paths are not normal settings sources.
~/.claude.json stores application state, not settings. The settings file must be inside the ~/.claude directory and named settings.json, unless CLAUDE_CONFIG_DIR relocates that directory.
Read the startup Settings Error, inspect /status, and run claude doctor or /doctor. Check for missing quotes and unmatched braces or brackets.
If the expected layer is missing or a file is listed with an error, check its path and syntax. Remember that /status does not report the origin of every key.
For scalar values: Managed > command line > Local > Project > User. Array settings are merged and deduplicated instead of being replaced wholesale.
Check CLAUDE_CONFIG_DIR, --settings, and --setting-sources. The first relocates the user configuration root; the flags can override explicit keys or limit loaded settings sources.
Local diagnostic
Run the browser-only checker to parse redacted JSON and examine path and scope fit, exact allow/deny conflicts, and common precedence or launch causes. Confirm its result with Claude Code and the official schema.
The most common causes are: (1) the file is in the wrong location — it must be at ~/.claude/settings.json, .claude/settings.json, or .claude/settings.local.json depending on scope; (2) the JSON is invalid, such as a missing quote or unmatched bracket; (3) a higher-precedence scope overrides a scalar value — Managed > command line > Local > Project > User, while array settings are merged and deduplicated; or (4) CLAUDE_CONFIG_DIR redirects the user config root or --setting-sources excludes a normal settings scope.
Run /status inside Claude Code to inspect the active settings layers and any files with settings errors. It does not report the source of every individual key. Current versions show a Settings Error at startup for invalid settings; terminal command claude doctor provides read-only details, and /doctor inside a session also runs configuration checks.
Yes. --settings accepts a settings file or inline JSON at command-line precedence, but it overrides only the keys it supplies; omitted keys can still come from the normal settings scopes. --setting-sources can limit which user, project, and local sources are loaded, while CLAUDE_CONFIG_DIR relocates the user configuration root.
Open Settings Check in your browser and enter your path, scope, launch context, and a redacted copy of your settings.json. The diagnostic parses the JSON and checks path and scope fit, exact allow/deny conflicts, and common precedence or launch causes without sending your data to a server. Then confirm the result with /status, /doctor, and the official settings schema.
Sources last reviewed August 11, 2026.