CertSafari
    Anthropic Claude Certified Architect – Professional (CCAR-P)· Lessons

    Domain 7 · Lesson 38/38

    Diagnose Claude Code configuration: what loaded and why

    Support debugging and operational issue resolution

    13 min read
    2.33% of exam
    2 sources
    Published 19 Oct 2026
    Docs as of 14 Oct 2026

    What you will be able to do

    • Use /memory, /hooks, /mcp, /permissions, /status and /doctor to see what a Claude Code session actually loaded before changing anything
    • Explain why a settings value, memory file, permission rule or hook can be present on disk yet have no effect
    • Tell apart a failed, an unapproved and a connected-but-zero-tools MCP server, and apply the right fix to each
    • Isolate a configuration fault with safe mode and with a clean configuration directory

    Key concept

    Diagnose from what loaded, not from what you wrote — A file on disk only tells you what someone meant to configure. Before you edit anything, ask the running session what it actually loaded and which source won. Then narrow down the cause by turning customizations off.

    1.Start from the symptom, then ask what loaded

    Most Claude Code complaints like "it ignores my settings" come down to one of three things: the configuration was never read, it was read and then overridden, or it was read and matched nothing. Re-reading your own JSON can't tell these apart, because the file looks correct in all three cases. The session can tell them apart, since each kind of customization has a slash command that reports what is in effect right now.

    Commands that report what the current session loaded
    CommandWhat it shows
    /memoryMemory file locations across user and project scopes, plus the auto memory folder and toggle
    /skillsAvailable skills from project, user, and plugin sources
    /hooksActive hook configurations
    /mcpConnected MCP servers and their status
    /permissionsResolved allow and deny rules currently in effect
    /statusActive settings sources, including whether managed settings are in effect
    /doctorSetup checkup: invalid settings files, unused extensions, duplicate subagent names, with proposed fixes
    /debug [issue]Turns on debug logging and asks Claude to diagnose from the log and settings paths

    Pick the command that matches the symptom. If a hook never fires, open /hooks. If a deny rule doesn't block, open /permissions. If you can't tell which layer is responsible, /status lists every settings source, including managed settings that no user file can override. A blank or unexpected result is your first real clue: you now know whether the problem is about loading, precedence or matching.

    Checkpoint 1 of 8· Match them up

    Something in your Claude Code configuration isn't taking effect. Match each slash command to what it reports about the running session.

    Tap a term, then the definition that fits it.

    Sources1

    2.Settings, memory files and permission rules that silently miss

    Precedence explains most "ignored" settings values. The order is settings.local.json, then the project settings.json, then the user ~/.claude/settings.json. A value one engineer keeps in their local file wins over what the team committed, and /status will still list the project file as active. A second common mistake is putting configuration in the wrong file. ~/.claude.json holds app state and UI toggles, while permissions, hooks and env belong in ~/.claude/settings.json. A rule added to the first file is never applied.

    Memory files can be correct and still not be loaded yet. When Claude seems to ignore guidance, open /memory to see which files the session knows about. Writing that guidance well is covered under CLAUDE.md as implementation guidance. Two loading rules catch people out. A subdirectory's CLAUDE.md loads on demand, not at session start, so it only appears once Claude reads a file in that subdirectory. Subagents are the other case: the built-in Explore and Plan agents skip CLAUDE.md at startup, so restate a critical instruction in the delegating prompt. A custom subagent that sets omitClaudeMd skips it too.

    Permission rules fail by not matching, not by erroring. How permission rules: allow, ask and deny are written is covered elsewhere. For diagnosis, the key fact is that a Bash rule matches the literal command string. Bash(rm *) therefore doesn't block /bin/rm or find -delete, and nothing warns you. Check /permissions for the resolved rules. When you need a hard guarantee, use a PreToolUse hook or the sandbox instead of a string pattern.

    Checkpoint 2 of 8· Check yourself

    Your team's deny rule Bash(rm *) shows up in /permissions. Claude still deleted files by running find . -name '*.tmp' -delete, and no warning appeared. What should you do?

    Checkpoint 3 of 8· Check yourself

    /memory lists the project CLAUDE.md, and the main conversation follows its rule "never touch the generated/ folder". When you hand a search to the built-in Explore agent, that agent ignores the rule. What fixes this?

    Checkpoint 4 of 8· Exam question

    An admin sets model: claude-opus-4-8 in the project's .claude/settings.json so the whole team defaults to Opus. One engineer's sessions keep starting on Sonnet instead, and /status confirms project settings are being read. What is the most likely explanation?

    Sources1

    3.Hooks that never fire

    A hook that never runs usually produces no error at all, which is why it is hard to spot. The mechanics of hooks: actions that always run are covered elsewhere. For debugging, start with /hooks. If the hook is missing from that list, it wasn't loaded. If it is listed but never fires, its matcher matches nothing.

    These causes come up again and again:

    • Standalone file: the hook sits in its own file. Project and user hooks go under the "hooks" key in settings.json; only plugins load a separate hooks/hooks.json.
    • Array matcher: the matcher is a JSON array instead of one string. Claude Code flags this as an invalid setting at startup and in claude doctor. Under PreToolUse or PermissionRequest it also stops every other hook in that file from loading.
    • Lowercase name: "bash" matches nothing, because matching is case-sensitive and tool names are capitalized (Bash, Edit, Write, Read).
    • Comma separator on an old version: before v2.1.191, "Edit,Write" was evaluated literally and never matched. "Edit|Write" works on every version.
    • Misspelled tool name: the matcher matches nothing, so the hook fails silently.

    Checkpoint 5 of 8· Match them up

    A teammate's hooks never run. Match each hook setup to what Claude Code does with it.

    Tap a term, then the definition that fits it.

    Sources1

    4.Three MCP failure states and their fixes

    "The MCP server isn't working" can mean three different states, and each has a different fix. /mcp shows which one you are in. Apply the fix for that state; a fix for one of the others won't help.

    MCP server states in /mcp, what each means, and the fix
    What /mcp showsWhat it meansFix
    failedThe server process didn't start; relative paths in command or args are a frequent cause, because they resolve against the launch directoryUse absolute paths for local scripts; executables on PATH like npx or uvx work as-is
    Not listed / disabled (project server)The one-time approval prompt for a server in .mcp.json was dismissedApprove it from /mcp
    connected, zero toolsThe server started but isn't returning a tool listSelect Reconnect; if still zero, run claude --debug=mcp and read the server's stderr in ~/.claude/debug/<session-id>.txt

    The zero-tools state is the one people misdiagnose most often. A connected server has already started, so path fixes and re-approval are both aimed at problems you don't have. The useful evidence is the server's own stderr, which only shows up in the debug log. Safe mode doesn't apply here either: it turns MCP servers off entirely, so a server that shows as connected is not running under safe mode.

    A server that never appears at all usually means the config file wasn't read. Project servers belong in .mcp.json at the repository root, not under .claude/, and they must sit under mcpServers rather than a VS Code-style servers key. settings.json doesn't read an mcpServers key at all. If a server starts but is missing environment variables, set them per server inside its .mcp.json entry.

    Checkpoint 6 of 8· Match them up

    Each line below describes an MCP server that isn't working. Match each one to the fix that addresses it.

    Tap a term, then the definition that fits it.

    Checkpoint 7 of 8· 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?

    Sources1

    5.Isolate the cause with safe mode or a clean config directory

    Isolation is for when the reporting commands look normal but the problem persists. Safe mode is the quick first step. Start with claude --safe-mode, or set CLAUDE_CODE_SAFE_MODE, and CLAUDE.md, skills, plugins, hooks, MCP servers, and custom commands and agents all stay unloaded. Authentication, model selection, built-in tools and permissions keep working. If the problem goes away, one of the disabled customizations is responsible. The same test works for runaway CPU or memory: if usage drops in safe mode, start looking at plugins, MCP servers and hooks.

    A clean configuration directory goes further and tells you which layer is at fault. Create an empty directory, then start Claude Code there with its config pointed at a fresh location and only user settings sources enabled:

    Step 1: create and enter an empty working directory (Bash or Zsh)bash
    mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty
    Step 2: launch with a clean configuration directorybash
    CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user

    Then reproduce the problem. If it's gone, the cause is in your user or project configuration. Copy ~/.claude.json and the files in ~/.claude into the clean directory one at a time until the problem comes back. If none of them brings it back, move to the project directory and launch without --setting-sources user. If the problem persists even in the clean setup, the cause is outside user and project configuration. Run /status to check for managed settings, then look at your shell's environment variables.

    Checkpoint 8 of 8· Fill the gap

    Safe mode made the problem go away. You now want to find out which configuration layer causes it, so you launch from an empty directory with a fresh config location. Which value completes the launch command?

    CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources  ? 

    Sources21

    Sources

    (2)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “Use /context, /doctor, /hooks, and /mcp to see what actually loaded.”
      ↩︎ Start from the symptom, then ask what loaded
      “Enables debug logging for the session and prompts Claude to diagnose using the log output and settings paths”
      ↩︎ Start from the symptom, then ask what loaded
      “~/.claude.json holds app state and UI toggles. permissions, hooks, and env belong in ~/.claude/settings.json.”
      ↩︎ Settings, memory files and permission rules that silently miss
      “Subdirectory files load on demand, not at session start”
      ↩︎ Settings, memory files and permission rules that silently miss
      “The built-in Explore and Plan agents skip CLAUDE.md at startup.”
      ↩︎ Settings, memory files and permission rules that silently miss
      “Bash rules match the literal command string, not the underlying executable”
      ↩︎ Settings, memory files and permission rules that silently miss
      “If the array is under PreToolUse or PermissionRequest, none of that file’s other hooks load either.”
      ↩︎ Hooks that never fire
      “Matching is case-sensitive. Tool names are capitalized: Bash, Edit, Write, Read.”
      ↩︎ Hooks that never fire
      “A server that fails to start shows as failed in /mcp.”
      ↩︎ Three MCP failure states and their fixes
      “If the prompt was dismissed, the server stays disabled until you approve it from /mcp.”
      ↩︎ Three MCP failure states and their fixes
      “run claude --debug=mcp and read the server’s stderr in the debug log at ~/.claude/debug/<session-id>.txt.”
      ↩︎ Three MCP failure states and their fixes
      “Problem persists: the cause is outside your user and project configuration.”
      ↩︎ Isolate the cause with safe mode or a clean config directory
      “Use /context, /doctor, /hooks, and /mcp to see what actually loaded.”
      ↩︎ Key concept
      “settings.local.json overrides settings.json, and both override ~/.claude/settings.json.”
      ↩︎ Exam trap 1
      “A server that shows as connected but lists zero tools has started successfully but isn’t returning a tool list.”
      ↩︎ Exam trap 2
      “A misspelled tool name produces a matcher that matches nothing, so the hook fails silently.”
      ↩︎ Exam trap 3
      “/status | Active settings sources, including whether managed settings are in effect”
      ↩︎ Checkpoint
      “settings.local.json overrides settings.json, and both override ~/.claude/settings.json.”
      ↩︎ Prediction
      “Use a PreToolUse hook or the sandbox for a hard guarantee.”
      ↩︎ Checkpoint
      “For Explore or Plan, restate the instruction in your delegating prompt.”
      ↩︎ Checkpoint
      “A server that shows as connected but lists zero tools has started successfully but isn’t returning a tool list. Select Reconnect from /mcp.”
      ↩︎ Checkpoint
    2. 2.
      “If a problem disappears in safe mode, one of those surfaces is the cause.”
      ↩︎ Isolate the cause with safe mode or a clean config directory
      “Authentication, model selection, built-in tools, and permissions still work.”
      ↩︎ Isolate the cause with safe mode or a clean config directory

    Continue to part 2 of 2

    Claude Code errors, automatic retries and session recovery

    Spotted a mistake, or was something unclear? Tell us.