Claude Code Config Not Taking Effect: Diagnosing with /context, /doctor, /mcp, and Error References

🌏 中文版

"I put that rule in CLAUDE.md and it keeps ignoring it." "My hook is defined but nothing fires." "I added an MCP server and the tool list is empty." This family of "configured it but it's not taking effect" problems is among the most reported in Claude Code. The official diagnostics guide narrows the cause down to three possibilities: the file never loaded, it loaded from a different location than you expected, or another file overrode it. This post is about telling those three apart: first inspect what actually loaded with the diagnostic commands, then bisect with safe mode, then match your symptom against a table of high-frequency errors. Installation and login problems are out of scope here — see the series' installation troubleshooting post.

Diagnostic entries: what each one shows

The core principle is one sentence: don't guess — look at what Claude Code actually loaded. The first step is always /context, which breaks down everything occupying the current session's context window by category: system prompt, built-in tools, MCP tools, subagents (with the source each loaded from), memory files, skills, and conversation messages. If your CLAUDE.md or skill doesn't appear in that breakdown at all, the problem is "didn't load" and there is no point guessing about behavior. Once you've confirmed something loaded, drill into its category:

From the terminal you can also run claude doctor, which prints read-only installation and settings diagnostics without starting a session — handy in scripts. If /context confirms that CLAUDE.md loaded but Claude still does not follow a specific instruction, the current docs move the diagnosis to instruction quality: whether the rule is specific, whether another file conflicts with it, and whether the file has grown too long for individual rules to receive attention.

Who overrode your setting

Settings merge across layers. The documented precedence is: managed settings at the top, then per-session command-line / --settings, then project local (.claude/settings.local.json), shared project (.claude/settings.json), and user (~/.claude/settings.json). Some keys also have environment-variable overrides, so check the settings reference for the exact key. The most common answer to "I set it but nothing happened" is not a bug — it's that the same key was also set in a higher-precedence source.

High-frequency landmines:

• ~/.claude.json is not a settings file. It is Claude Code's own state file: sign-in session, some MCP configurations, project trust decisions, and global config keys written by /config. permissions, hooks, and env belong in ~/.claude/settings.json.
• MCP server configuration does not go in settings.json. Project-scoped servers live in .mcp.json at the repository root (under the mcpServers key — not servers, VS Code style); user-scoped servers are added with claude mcp add --scope user, which lets the CLI write the right place. A remote HTTP JSON entry with a url also needs type: "http" (or sse / ws); without type, Claude Code now reports it as a configuration error.
• Project .mcp.json requires one-time approval and workspace trust. Dismiss the approval prompt once and the server stays disabled; re-approve it from /mcp. A cloned repository cannot approve its own servers through committed approval settings before the workspace is trusted. Use user settings, managed settings, or --settings if approval must apply before trust.
• Read the /mcp status detail, not just presence. A remote server can be cached ... connects on first use, Pending approval, Disabled for this project, Failed to connect, or not configured. If it is connected but shows zero tools, reconnect it from /mcp; if the count stays at zero, run claude --debug=mcp and inspect the server stderr in ~/.claude/debug/<session-id>.txt.
• A hook's matcher is a single string; separate multiple tools with | (as in "Edit|Write"). Claude Code v2.1.191 and later also treat a comma as a separator; only earlier versions treated the comma as a literal and silently matched nothing. Tool names are case-sensitive: bash will not match Bash. And a matcher written as an array is a schema error: Claude Code rejects hooks from that user/project/local settings file; managed settings drop that file's whole hooks key while keeping the other settings. claude doctor reports the validation failure.

Safe mode: bisecting the culprit

If the targeted diagnostic entries haven't isolated the layer yet, launch claude --safe-mode: a session with every customization disabled — CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents — while authentication, model selection, built-in tools, and permissions work normally.

The result is binary:

• The problem disappears in safe mode → the cause is one of your customizations; go back to the targeted checks above to find which.
• The problem persists in safe mode → narrow further to a clean environment: cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude, bypassing everything under ~/.claude and loading no project configuration. If the problem vanishes here, reintroduce your files one at a time to find the culprit; if it persists even here, the cause lies outside your user and project configuration — run /status to check whether managed settings apply, then look for environment variables affecting Claude Code.

Note that organization-managed hooks and settings policy still apply in safe mode; they are the only thing carried in.

Common error messages

Beyond configuration, the other big blocker category is runtime errors. There is a full official error reference; below are six of the highest-frequency entries condensed into a table (the official page remains the authoritative list):

One more thing worth knowing: Claude Code automatically retries transient failures up to 10 times with exponential backoff, so by the time any of these errors reaches you, every applicable retry has already happened — act on the error rather than wondering whether you should have waited longer.

Two worked cases

Both paths have full write-ups on this site:

• Global skills not found: global skills invisible in new sessions — a textbook case of the "file never loaded" branch.
• Spinner verbs stuck: frozen spinner verbs — the runtime-problem investigation path.

Finally, how these three posts divide the territory: can't install or log in, read the installation & login post; crashes mid-run, performance anomalies, interrupted responses, read the runtime post; "configured but not taking effect" is this one. For the series map and underlying mechanics, start from the entry post.

References

• Debug your configuration — Claude Code Docs — Official guidance on diagnosing with /context, /doctor, /hooks, and /mcp, safe mode and clean-config comparison, plus the common configuration pitfalls table
• Error reference — Claude Code Docs — The complete runtime error catalog: meaning and recovery steps per message, automatic retry behavior, and tunable environment variables
• Claude Code settings — Claude Code Docs — Settings files, precedence, and the split between ~/.claude.json and settings files
• Connect Claude Code to tools via MCP — Claude Code Docs — MCP transports, .mcp.json, approval / trust, server status, discovery cache, and common configuration warnings

Changelog

• 2026-08-29: Updated /skills, /permissions, /debug [issue], settings precedence, hook matcher, MCP approval/cache/status details, and error wording.
• 2026-08-26: Initial version, written against the official Debug your configuration and Error reference pages.