← Blog · 2026-10-17

Claude Code Settings Not Applying? 12 Causes and Fixes

Shortcut: paste your settings files into our free settings precedence checker. It shows the value Claude Code ends up using for every key, which file won, which entries are ignored because they're in the wrong file, and how your permission rules merge. It runs in your browser.

Claude Code reads settings from four JSON files, and an organization can add managed settings on top:

When you set a key and Claude Code acts as if you hadn't, one of four things is going on: another level sets the same key, the file you used can't set that key, the file didn't load, or the setting applied and works differently than you expected. Work through the checks below in order.

First: see what loaded

Run /status inside Claude Code. The Setting sources line lists every settings file Claude Code loaded for this session, such as User settings or Project local settings, and names the managed source if your organization has one. It tells you which files were read, not which file supplied each key.

Then run claude doctor in your terminal. It lists entries Claude Code rejected, without starting a session.

Another level wins: 4 causes

1. A higher settings file sets the same key. For a single value, Claude Code uses the highest level that sets it. Highest first: managed settings, then --settings on the command line, then .claude/settings.local.json, then .claude/settings.json, then ~/.claude/settings.json. So if you turn spinnerTipsEnabled off in your user file and the team's .claude/settings.json turns it on, the project value wins in that project. Fix: to get your value back for yourself only, put the key in .claude/settings.local.json, which sits above the shared project file and isn't committed.
2. An old value is sitting in settings.local.json. Claude Code writes this file itself: when you pick "Yes, and don't ask again" on a permission prompt it saves an allow rule there, and a few /config options such as Show tips save there too. Since v2.1.211, inside a git repository Claude Code keeps it at the repository root, even when you start in a subdirectory. An older copy that an earlier version left in the starting directory is still read; where both set the same key, the root file wins. Fix: open the local file at the repository root and remove the stale key.
3. Your organization manages that key. Nothing in your own files or --settings overrides a managed key. /status names the managed source. One nuance: a managed model is a starting default, not a lock (the locks are availableModels and deniedModels). Fix: ask your administrator; you can't override it locally.
4. A flag or environment variable overrides the file. Environment variables aren't a level in the stack; each pair is decided on its own. --model beats an exported ANTHROPIC_MODEL, and both beat the model key from any file, even managed. CLAUDE_CODE_EFFORT_LEVEL beats --effort, and both beat effortLevel. --permission-mode beats defaultMode. On the other hand ANTHROPIC_DEFAULT_MODEL applies only when no file sets model. Fix: unset the variable or drop the flag (check your shell profile and any wrapper script). Each key's entry in the settings reference lists its overrides.

The file can't set that key: 3 causes

5. The key isn't allowed in that file. Every key has a scope. Some are user-or-managed only, such as modelPicker and autoMode, so Claude Code ignores them in project and local files. Others are managed only, such as allowManagedHooksOnly. And "global config" keys apply only from ~/.claude.json, so they do nothing in any settings.json. Fix: look the key up in the Scope column of the settings index and move it to a file that can set it.
6. defaultMode is auto or bypassPermissions in a project file. These two values don't take effect from .claude/settings.json or .claude/settings.local.json. (Before v2.1.257, bypassPermissions worked from any file, which is why an old setup may have stopped working after an update.) Fix: set it in ~/.claude/settings.json, or pass --permission-mode for one session. If disableBypassPermissionsMode is set to "disable" anywhere, bypass mode is off no matter what.
7. The variable in your env block is one a project can't set. Project and local settings can't set variables a cloned repository shouldn't control, including CLAUDE_CONFIG_DIR, CLAUDE_CODE_TMPDIR, HOME, TMPDIR and the XDG_* family, and (from v2.1.282) the OpenTelemetry variables that turn telemetry on or choose where it goes. Claude Code drops them and logs a warning you can see with claude --debug. Values that turn telemetry off, such as none for the exporter selectors, still apply. Fix: set those variables in your shell, user settings or managed settings.

The file didn't load: 3 causes

8. The setting is in the wrong file or folder. ~/.claude.json (no folder) is a different file from ~/.claude/settings.json: it holds app state, and permissions, hooks and env added there are ignored. settings.json doesn't read an mcpServers key either; project MCP servers go in .mcp.json at the repository root. And Claude Code reads .claude/settings.json from the session's primary working directory, with no parent-directory fallback, so a file committed at the repository root doesn't load when you start Claude Code in a subfolder. Fix: move the key to the right file, and start Claude Code from the folder that holds .claude/.
9. The JSON is broken. Settings files are strict JSON: a // comment or a trailing comma is a syntax error. Claude Code shows a Settings Error at the next interactive start and lets you fix the file, exit, or continue without it. If only one entry is bad, such as a malformed permission rule, you get a Settings Warning and just that entry is skipped. A claude -p run shows no dialog at all; it skips the broken file or entries and carries on. Fix: remove comments and trailing commas, then run claude doctor to see anything else it dropped. Adding "$schema": "https://json.schemastore.org/claude-code-settings.json" gives you autocomplete and validation in editors that support JSON schema.
10. The folder isn't trusted yet. Allow rules and additionalDirectories in .claude/settings.json apply only after you accept that folder's trust dialog, and the same goes for extraKnownMarketplaces and most env values. Deny and ask rules apply right away. claude -p never shows the dialog, so a project's allow rules don't apply in an untrusted -p run. Your local file normally skips the trust step, but not if it's tracked by git or .claude is a symlink. Fix: start an interactive session in the folder and accept the trust dialog, and keep settings.local.json out of git.

It applied, just not how you expected: 2 causes

11. Lists merge instead of replacing. For a list key such as permissions.allow, Claude Code combines the entries from every file, so leaving a rule out of a higher file doesn't remove it from a lower one. Permission rules are then checked deny first, then ask, then allow: a deny from any file beats an allow from any other, and an allow rule saved by "Yes, and don't ask again" doesn't outrank an ask rule in a project or managed file. A few model keys don't merge: fallbackModel is taken whole from the highest file, and so is modelPicker (from managed, --settings or user settings only). Fix: to stop a rule, add a deny or ask rule rather than deleting an allow rule somewhere else. Our permissions builder shows which rule decides a given command.
12. The key is only read at session start. Claude Code watches your settings files and applies most edits without a restart, including permissions and hooks. A few keys are read once, at startup, notably model (use /model to switch mid-session) and effortLevel and modelSettings (use /effort). Managed settings delivered by MDM or the admin console arrive on a schedule rather than on save. Fix: restart the session, or use the in-session command.

Two special cases

• Some security keys keep their strict value. For a handful of keys Claude Code honors the restrictive value even over managed settings. For example, disableClaudeAiConnectors: true from any file stays on, a project or local remoteControlAtStartup: false wins over a managed true, and when several files set maxEffortLevel the lowest cap applies.
• Cloud sessions read fewer files. A cloud session runs on a fresh clone, so it doesn't read your ~/.claude/settings.json or .claude/settings.local.json. In a single-repository session it reads the committed .claude/settings.json; your organization's server-managed settings reach it too, but a managed settings file on your laptop doesn't.

Quick reference

Make a value win for just you

To change a setting for yourself in one project without touching the team file, add it to .claude/settings.local.json in that project:

{
  "spinnerTipsEnabled": false
}

Local sits above shared project and user settings, so only your sessions there change. If you created the file by hand, add it to .gitignore.

Facts on this page come from Anthropic's settings files and precedence guide, settings reference, permissions docs and debug your configuration guide. Behavior changes between versions, so update Claude Code before you debug further. This guide isn't affiliated with Anthropic.

If you use Claude Code for client work, skills take care of the repeat jobs. Start with our free 3-skill sample (client follow-ups, meeting notes to tasks, invoice chasing), or get the full Solo Consultant Kit.