Debugging Your Configuration

When Claude ignores your instructions or a feature you configured doesn't show up, the cause is almost always one of three things:

1. The file didn't load
2. It loaded from a different location than you intended
3. Another file overrode it by precedence

This chapter covers the diagnostic commands that show what Claude Code actually loaded, plus the pitfalls you'll run into most often.

tip

For install/login-stage problems, see the Level 1 installation chapter first; for runtime error messages, see the Level 2 error catalog. This chapter is dedicated to the "my configuration isn't taking effect" case.

The First Command Is /context

/context shows your current session's context window by category — system prompt, memory, skills, MCP tools, messages. It's the first place to check whether your CLAUDE.md, rules, and skill descriptions loaded at all.

(Velog log #38 covers /context usage patterns.)

Diagnostic Commands by Category

Command	What it shows
/memory	Loaded CLAUDE.md and rule files + auto-memory entries
/skills	Available skills by source: project, user, plugin
/agents	Wizard removed in v2.1.198 — check subagent loading via /context (shown by source); to create or manage subagents, ask Claude or edit .claude/agents/ directly
/hooks	Active hook configuration
/mcp	Connected MCP servers and their status
/permissions	Currently applied allow/deny rules
/doctor	Full setup checkup (v2.1.205+, alias /checkup) — diagnoses install state, malformed settings files, unused extensions, duplicate subagent names within the same directory, and trimming suggestions for a checked-in CLAUDE.md (v2.1.206+), and applies fixes after confirmation
/debug [issue]	Enables debug logging for the session + Claude reads the logs and diagnoses
/status	Active settings sources — including whether managed settings apply

Order: /context → the relevant category command → /doctor (full checkup)

CLAUDE.md Isn't Loading

If the file doesn't appear in /memory, it's a location problem:

• Subdirectory CLAUDE.md files are not auto-loaded at session start. They load on demand, when Claude reads a file in that directory with the Read tool. So not seeing them at first is normal
• If it shows up in /memory but Claude doesn't follow it, that's not a loading problem — it's how the instructions are written. They're ambiguous, two files conflict, or the file is so long that attention to individual rules drops

(Velog log #47 covers how to decide between /compact and a fresh session.)

Settings Precedence

Settings merge across 4 scopes: managed, user, project, local.

• If managed settings exist, they always win
• The rest take precedence in the order local → project → user (the closer scope wins)
• Command-line flags and environment variables are yet another override layer

Use /status to see which sources are active. To determine which scope wins, see the official settings docs.

An MCP Server Won't Connect

Check the status in the /mcp output:

• Project-scope .mcp.json servers need one-time approval — if you dismiss the first-entry prompt, the server stays inactive. Re-approve it from /mcp
• If startup fails, it shows as failed. Relative paths in command/args resolve against the directory Claude Code started in, not the .mcp.json location, so they break often. Absolute paths recommended
• Connected but 0 tools means the server started but returned no tool list. Hit Reconnect in /mcp. Still 0? Check the server's stderr with claude --debug mcp

A Hook Isn't Firing

If it doesn't show up in /hooks, it wasn't read. Hooks must live under the "hooks" key in settings.json — not in a separate file.

If it shows in /hooks but still doesn't fire, it's almost always a matcher problem:

Pitfall	Fix
matcher is a JSON array	Use a single string. To match multiple tools, use | — e.g. "Edit|Write"
matcher is lowercase — "bash"	Case-sensitive. Tool names are capitalized — Bash, Edit, Write, Read
Typo in the tool name	Silently fails to match

After editing settings.json, changes apply automatically after a short file-stability delay. No restart needed. Run /hooks again after a few seconds.

If it's genuinely not being caught, watch hook evaluation live with claude --debug hooks — every event, matcher check, exit code, and output gets logged.

Change Settings Right from the Prompt — /config key=value

You can change a value straight from the prompt to test it, without opening the settings file (v2.1.181+). Works in interactive, -p, and Remote Control alike:

/config thinking=false

See the full list of shorthand keys with /config --help (v2.1.183+). Running /config with no arguments opens the toggle UI; as of v2.1.183, both Enter and Space change the selected item, and Esc saves and closes (rather than reverting).

tip

When you're diagnosing a pitfall and think "if I could just turn this one setting off," use /config key=value to flip it instantly — no file editing, no restart — and check whether the issue reproduces.

Compare Against a Clean Session

If targeted diagnostics don't find the cause, or you're unsure what state your configuration is in, compare against a session that loads none of your usual configuration.

The fastest way is the --safe-mode flag (v2.1.169+). It launches with all customizations disabled — CLAUDE.md, plugins, skills, hooks, MCP servers — so you can see whether the problem reproduces:

claude --safe-mode
# also available as an environment variable: CLAUDE_CODE_SAFE_MODE=1

If the problem disappears with --safe-mode, the cause is somewhere in your customizations. To isolate further, down to credentials and the config directory, point CLAUDE_CONFIG_DIR at an empty directory and start in a directory with no .claude, .mcp.json, or CLAUDE.md:

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

A clean session has zero user/project settings, hooks, MCP servers, plugins, or memory.

• Only managed settings still apply, since they live at a system path
• Linux and Windows will ask you to log in again (credentials are stored inside the config directory)
• macOS keeps your credentials, since they live in the Keychain

If the problem disappears in the clean session → the cause is inside your ~/.claude or the project's .claude. Add pieces back one at a time to find the culprit.

If it still reproduces in the clean session → it's outside your user/project settings. Check for managed settings influence with /status, and review environment variables.

The 12 Most Common Pitfalls

Symptom	Cause	Fix
Hook doesn't fire	matcher is an array or lowercase	Single string + capitalized — "Edit|Write", "Bash"
Hook doesn't fire	Hook is in a standalone file	Put it under the "hooks" key in settings.json (only plugins use a separate hooks/hooks.json)
permissions, hooks, env ignored globally	Added to ~/.claude.json	~/.claude.json is app state only. These keys go in ~/.claude/settings.json
settings.json value ignored	Same key exists in settings.local.json	settings.local.json > settings.json > ~/.claude/settings.json
Skill missing from /skills	Placed at .claude/skills/name.md	Folder structure — .claude/skills/name/SKILL.md
Skill visible but Claude never invokes it	disable-model-invocation: true, or the description doesn't match how you phrase requests	Check for the "user-only" badge in /skills
Subdirectory CLAUDE.md ignored	On-demand loading — loads only when Claude reads a file in that directory with the Read tool	Normal. Not auto-loaded at startup
Subagent ignores CLAUDE.md	Built-in Explore and Plan skip CLAUDE.md	For Explore/Plan, restate it in the delegation prompt. For custom subagents, put it in the agent file body
No cleanup on session end	SessionEnd hook not configured	Add it to settings.json
Project MCP server doesn't start	Placed inside .claude/ or using the Claude Desktop format	.mcp.json at the repository root
Added mcpServers to settings.json	settings.json does not read the mcpServers key	.mcp.json (project) or claude mcp add --scope user
Environment variables missing when an MCP server starts	settings.json env does not propagate to MCP child processes	Use per-server env inside .mcp.json

Summary

First suspicion	Command
Don't know what loaded	/context → then /memory, /skills, /hooks, /mcp
Multiple settings sources conflicting	/status (check active sources) + /doctor (validate)
Hook doesn't fire	Confirm registration with /hooks → check matcher case, arrays, key location → claude --debug hooks
MCP not picked up	/mcp → check approval status, startup failure, 0 tools → switch to absolute paths → claude --debug mcp
Can't find the cause	Compare quickly with claude --safe-mode → if that's not enough, CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

This chapter is based on the official debugging page, organized around the cases readers hit most often. For the latest pitfall list, the official docs are the source of truth.

---

Next chapter: Hooks Automation →