What you will be able to do
- Match a Claude Code symptom to the diagnostic command that shows what actually loaded
- Find out whether a customization is the cause by running a safe-mode or clean-config session
- Work out why an MCP server shows as failed, or as connected with zero tools
- Recognise the common reasons a hook or setting is silently ignored
Key concept
Inspect what actually loaded — When Claude Code is misbehaving, don't trust the config file you think you wrote. Use the built-in diagnostic commands to see which settings, hooks, MCP servers and rules are actually in effect, and compare that with what you expected.
1.Start from the symptom, then ask Claude Code what it loaded
The troubleshooting docs are organised by symptom. Install, PATH and TLS problems go to the installation page. API messages such as 5xx, 529 Overloaded and 429 go to the error reference. "Settings not applying, hooks not firing, MCP servers not loading" go to the configuration debugging page. Slow responses, hangs and high memory go to the performance section. For a quick first check in any session, the docs recommend you "Run /doctor for a setup checkup and /mcp to check MCP server status".
Most configuration bugs have the same shape: the file on disk says one thing, but the session is running with something else. Each slash command below shows one layer of what the session actually loaded, so you can compare it with what you expected.
| Command | Shows |
|---|---|
| /doctor | Setup checkup: installation health, invalid settings files, unused extensions, duplicate subagent names, with proposed fixes |
| /mcp | Connected MCP servers and their status |
| /hooks | Active hook configurations |
| /permissions | Resolved allow and deny rules currently in effect |
| /status | Active settings sources, including whether managed settings are in effect |
| /debug [issue] | Enables debug logging for the session and prompts Claude to diagnose using the log output and settings paths |
Checkpoint 1 of 7· Match them up
Match each question you're trying to answer to the command that answers it
Tap a term, then the definition that fits it.
Each command shows one layer of what loaded. /status shows settings sources, /permissions shows the resolved rules, /debug turns on logging and starts a diagnosis, and /doctor checks the setup, including invalid settings files.
“Active settings sources, including whether managed settings are in effect”Source: code.claude.com
Checkpoint 2 of 7· Exam question
During a long debugging session, Claude Code raises "Autocompact is thrashing: the context refilled to the limit..." immediately after automatic compaction completes, and it stops retrying. The team was asking Claude to read an entire 40,000-line production log file to find the root cause of an outage. What is the most effective way to recover and continue the investigation?
Correct answer: B — Ask Claude to read the log file in smaller chunks, such as a specific line range, or delegate the analysis to a subagent instead.
- A. Incorrect. CLAUDE_CODE_MAX_RETRIES governs retries of failed API requests, not the compaction-thrashing loop. Thrashing happens because the file itself refills the context after each compaction, so retrying compaction more times does not solve the underlying problem.
- B. Correct. Auto-compaction succeeded but the oversized file output immediately refilled the context window several times in a row, so Claude Code stopped retrying to avoid wasted API calls. Reading the file in smaller chunks or moving the work to a subagent's separate context window is the documented recovery path.
- C. Incorrect. Disabling auto-compaction removes the safeguard that prevents the context window from overflowing, so it would make the thrashing problem worse, not better, since the full log would still need to fit in context.
- D. Incorrect. This is more drastic than necessary and discards useful investigation context. The documented recovery steps are to chunk the file, use a targeted /compact, or delegate to a subagent, not to abandon the conversation entirely.
2.Isolate the cause: safe mode and a clean config directory
If you can't tell whether one of your customizations is causing the problem, take them out of the picture. The troubleshooting page suggests you "Restart with claude --safe-mode to check whether a plugin, MCP server, or hook is the source." Safe mode turns off every customization for that session. If the CPU, memory or odd behaviour goes away, the cause is one of your customizations, and you narrow it down from there.
A stronger test is a session with an empty configuration directory, started from a neutral working directory. You'll be asked to log in again because the clean directory holds no credentials. This test has one limit you need to know: it does not remove organization policy. Managed settings come from MDM profiles, registry policy and managed-settings.json, which are read from outside the configuration directory, and server-managed settings are fetched again once you sign in. So if a problem still shows up in a clean session, it may be coming from managed policy.
Checkpoint 3 of 7· Fill the gap
Which environment variable points Claude Code at an empty configuration directory for a clean-session test?
cd /tmp && ? =/tmp/claude-clean claudeCLAUDE_CONFIG_DIR changes which configuration directory Claude Code reads. CLAUDE_CODE_TMPDIR only moves the temp directory.
Source: code.claude.comCheckpoint 4 of 7· Check yourself
A developer runs a clean-config session and a blocked behaviour still happens. What is the most likely explanation?
A clean configuration directory removes user-level config. Managed policy still applies because it comes from MDM, registry or managed-settings.json locations, and server-managed settings are fetched again once you sign in.
“Managed settings still apply if your organization deploys them.”Source: code.claude.com
3.MCP servers: failed, unapproved, or connected with zero tools
/mcp can show several different MCP problems, and each one has its own cause.
Not there at all. Servers defined in a project's .mcp.json need a one-time approval. "If the prompt was dismissed, the server stays disabled until you approve it from /mcp." Location matters too. Project MCP config goes in .mcp.json at the repository root, not inside .claude/, and the servers must sit under an mcpServers key. A top-level servers key, as in VS Code's file, won't load. Also, "settings.json does not read an mcpServers key", so servers added there never appear.
Failed. A common cause is a relative path in command or args, because relative paths "resolve against the directory you launched Claude Code from rather than the location of .mcp.json". That's why a server can work from one directory and fail from another. Use absolute paths for local scripts. If the server is missing environment variables, set them in the server's own env entry in .mcp.json.
Connected, zero tools. Here the server process is running, so the fix is to find out what the server is saying. Follow the steps below.
Checkpoint 5 of 7· Put it in order
Put the steps for a server that is connected but lists zero tools in the order the docs give
- 1.Read the server's stderr in the debug log at ~/.claude/debug/<session-id>.txt
- 2.If the tool count stays at zero, run claude --debug=mcp
- 3.Open /mcp and select Reconnect on the server
Reconnect first. If that doesn't fix it, start a debug session for MCP and read the server's stderr in the session's debug log.
“Select Reconnect from /mcp. If the count stays at zero, run claude --debug=mcp”Source: code.claude.com
Checkpoint 6 of 7· Exam question
A team's project relies on an internal MCP server for ticket lookups. Running /mcp shows the server status as connected, but Claude reports it has no tools available from that server and cannot look up tickets. What is the correct next step to diagnose the failure?
Correct answer: A — Select Reconnect for the server from /mcp, and if the tool count stays at zero, run claude --debug mcp to see the server's stderr output.
- A. Correct. A server that shows connected but lists zero tools has started but isn't returning a tool list. The documented step is to select Reconnect from /mcp, and if the count stays at zero, run claude --debug mcp to inspect the server's stderr output.
- B. Incorrect. A relative path in command or args typically causes the server to fail to start entirely, which shows as failed in /mcp, not connected with zero tools. That is not the situation described here.
- C. Incorrect. Project-scoped approval does not silently expire; once approved, a server stays enabled. This does not explain a connected server returning no tools.
- D. Incorrect. Safe mode disables all MCP servers for the session, so the server would not show as connected at all, let alone connected with zero tools. This is not a diagnostic step for this symptom.
Sources2
4.Silent failures in hooks, settings and permission rules
Hooks often fail without showing any error. "A misspelled tool name produces a matcher that matches nothing, so the hook fails silently." The same thing happens with lowercase tool names. "Matching is case-sensitive. Tool names are capitalized: Bash, Edit, Write, Read." A matcher is a single string, such as "Edit|Write". If you write it as a JSON array, that's a schema error that "rejects the whole user, project, or local settings file", so none of that file's hooks load. In managed settings, only the hooks key is dropped. On versions before v2.1.191, a comma separator matches nothing, so use |.
Other settings go missing because they're in the wrong file. "~/.claude.json holds app state and UI toggles. permissions, hooks, and env belong in ~/.claude/settings.json." There is no standalone hooks file for user or project config, and plugins are the only exception. A value can also be overridden: "settings.local.json overrides settings.json, and both override ~/.claude/settings.json."
Permission rules can be weaker than they look. A Bash(rm *) deny rule doesn't block /bin/rm or find -delete, because "Bash rules match the literal command string, not the underlying executable". When you need a hard guarantee, use a PreToolUse hook or the sandbox.
Checkpoint 7 of 7· Check yourself
A team lead adds a permissions block and a PreToolUse hook to ~/.claude.json. Neither takes effect. Why?
These are two different files. ~/.claude.json stores app state, so permissions, hooks and env placed there are ignored.
“~/.claude.json holds app state and UI toggles. permissions, hooks, and env belong in ~/.claude/settings.json.”Source: code.claude.com
Sources2
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.A Bash(rm *) deny rule stops Claude from deleting files by any route.Why is that wrong?
Bash rules match the literal command string, so /bin/rm or find -delete gets past the rule. Use a PreToolUse hook or the sandbox when you need a hard guarantee.
Covered in Silent failures in hooks, settings and permission rules
2.Putting MCP servers under an mcpServers key in settings.json, or in .claude/.mcp.json, is enough to load them.Why is that wrong?
Project servers belong in .mcp.json at the repository root, under mcpServers. settings.json does not read that key at all.
Covered in MCP servers: failed, unapproved, or connected with zero tools
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/troubleshootingOfficial docs
“Run /doctor for a setup checkup and /mcp to check MCP server status”
↩︎ Start from the symptom, then ask Claude Code what it loaded“Restart with claude --safe-mode to check whether a plugin, MCP server, or hook is the source.”
↩︎ Isolate the cause: safe mode and a clean config directory - 2.https://code.claude.com/docs/en/debug-your-configOfficial docs
“Enables debug logging for the session and prompts Claude to diagnose using the log output and settings paths”
↩︎ Start from the symptom, then ask Claude Code what it loaded“Managed settings still apply if your organization deploys them.”
↩︎ Isolate the cause: safe mode and a clean config directory“they resolve against the directory you launched Claude Code from rather than the location of .mcp.json”
↩︎ MCP servers: failed, unapproved, or connected with zero tools“If the prompt was dismissed, the server stays disabled until you approve it from /mcp.”
↩︎ MCP servers: failed, unapproved, or connected with zero tools“A misspelled tool name produces a matcher that matches nothing, so the hook fails silently.”
↩︎ Silent failures in hooks, settings and permission rules“settings.local.json overrides settings.json, and both override ~/.claude/settings.json.”
↩︎ Silent failures in hooks, settings and permission rules“Use /context, /doctor, /hooks, and /mcp to see what actually loaded.”
↩︎ Key concept“Bash rules match the literal command string, not the underlying executable”
↩︎ Exam trap 1“Project MCP config goes at the repository root as .mcp.json, not inside .claude/, with servers under the mcpServers key.”
↩︎ Exam trap 2“Active settings sources, including whether managed settings are in effect”
↩︎ Checkpoint“A server that shows as connected but lists zero tools has started successfully but isn’t returning a tool list.”
↩︎ Prediction“Select Reconnect from /mcp. If the count stays at zero, run claude --debug=mcp”
↩︎ Checkpoint“~/.claude.json holds app state and UI toggles. permissions, hooks, and env belong in ~/.claude/settings.json.”
↩︎ Checkpoint