Debug your configuration changeddebug-your-config
Upstream edited this page at 11 Oct 2026 19:36 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 11 Oct 2026 19:37 UTC.
Upstream edited
Recorded here
Lines+50added
Lines−8removed
From line
84
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits22to this page, all time
The whole hunk
from line 84, old and new numbered
/
from line 84
8484
8585Safe mode still applies managed hooks and settings policy from your organization. Managed plugins, skills, `CLAUDE.md`, and MCP servers are turned off.
8686
87If the problem persists in safe mode, or your settings themselves are suspect, compare against a session that loads nothing from your usual setup. Point [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars) at an empty directory to bypass everything under `~/.claude`, and launch from a directory that has no `.claude` folder, `.mcp.json`, or `CLAUDE.md` so project configuration is also skipped.
87If the problem persists in safe mode, or your settings themselves are suspect, start a session with none of your own configuration and check whether the problem follows.
8888
89```bash theme={null}
90cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
91```
89<Steps>
90 <Step title="Create an empty directory and change into it">
91 In your shell, with no Claude Code session running, create the directory and move into it:
9292
93The clean session has no user or project settings, hooks, MCP servers, plugins, or memory. On the first launch, expect the first-run setup screens, starting with theme selection. If you see them, the clean configuration directory is in effect. Later launches with the same directory skip these screens because Claude Code saves onboarding state there.
93 <Tabs>
94 <Tab title="Bash or Zsh">
95 ```bash theme={null}
96 mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty
97 ```
98 </Tab>
9499
95* Managed settings still apply if your organization deploys them. Claude Code reads MDM profiles, registry policy, and `managed-settings.json` from locations outside the configuration directory, and [fetches server-managed settings](/docs/en/server-managed-settings#fetch-and-caching-behavior) again for the clean session once it has credentials
96* You'll be prompted to log in again
100 <Tab title="PowerShell">
101 ```powershell theme={null}
102 New-Item -ItemType Directory -Force "$HOME/claude-clean/empty" | Out-Null
103 Set-Location "$HOME/claude-clean/empty"
104 ```
105 </Tab>
106 </Tabs>
107 </Step>
97108
98If the problem disappears here, the cause is somewhere in your real `~/.claude` or project `.claude` files. Reintroduce them one at a time, by copying files into the temporary directory or by launching from your project, to find which one. If it persists in the clean session, the cause is outside your user and project configuration. Run `/status` to check whether managed settings are in effect, look for [environment variables](/docs/en/env-vars) that affect Claude Code, then see [Troubleshooting](/docs/en/troubleshooting).
109 <Step title="Start Claude Code with a clean configuration directory">
110 From the same shell, set [`CLAUDE_CONFIG_DIR`](/docs/en/env-vars) to a fresh directory in place of `~/.claude`, and pass [`--setting-sources user`](/docs/en/cli-reference#cli-flags) to turn off project configuration such as `.claude/settings.json`, `CLAUDE.md`, and `.mcp.json`:
111
112 <Tabs>
113 <Tab title="Bash or Zsh">
114 The variable applies to this one launch.
115
116 ```bash theme={null}
117 CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user
118 ```
119 </Tab>
120
121 <Tab title="PowerShell">
122 The variable stays set for the rest of this PowerShell session, so later `claude` launches in the same window keep using the clean directory. To return to your usual directory, run `Remove-Item Env:CLAUDE_CONFIG_DIR` before the next launch.
123
124 ```powershell theme={null}
125 $env:CLAUDE_CONFIG_DIR = "$HOME/claude-clean/config"
126 claude --setting-sources user
127 ```
128 </Tab>
129 </Tabs>
130
131 On the first launch, you go through the first-run setup screens again, a sign that the clean configuration directory is in effect. Managed settings still apply, and [connectors](/docs/en/mcp#use-mcp-servers-from-claude-ai) still load if you log in with a claude.ai account.
132 </Step>
133
134 <Step title="Reproduce the problem">
135 Repeat what triggered the problem in the clean session:
136
137 * **Problem gone**: the cause is in your user or project configuration. Copy `~/.claude.json` and the files in `~/.claude` into `~/claude-clean/config` one at a time. If none brings the problem back, go to your project directory in the same shell and start Claude Code without `--setting-sources user`. In Bash or Zsh, run `CLAUDE_CONFIG_DIR=~/claude-clean/config claude`. In PowerShell, the variable is still set, so run `claude`.
138 * **Problem persists**: the cause is outside your user and project configuration. Run `/status` in the session to check for managed settings, check your shell for [environment variables](/docs/en/env-vars), then see [Troubleshooting](/docs/en/troubleshooting).
139 </Step>
140</Steps>
99141
100142## Check common causes
101143
No line in this hunk matches that.