Troubleshooting Claude Code configuration that does not take effect

Who this is for and what you will be able to do

This guide is for people who have configured Claude Code and find that an instruction is ignored, a hook never runs, or an MCP server or skill is missing. After reading it, you can check what actually loaded in a session, find the scope that overrides your setting, isolate the problem with safe mode or a clean configuration, and read the most common error messages.

Start by checking what loaded

Most surprises come from one of three things: the file did not load, it loaded from a different place than you expected, or another file overrode it^[1].

Run /context first. It shows everything in the context window, grouped into the system prompt, system tools, MCP tools, custom subagents, memory files, skills and conversation messages. It tells you whether your CLAUDE.md, rules or skill descriptions are there at all^[1]. In fullscreen mode it collapses the per-item breakdown, so run /context all to expand it^[1].

For a closer look at one category, use the matching command^[1]:

• /memory lists memory file locations across user and project scopes, and lets you open each file in your editor.
• /skills lists skills from project, user and plugin sources.
• /hooks lists the active hook configurations.
• /mcp shows connected MCP servers and their status.
• /permissions shows the allow and deny rules in effect.
• /status shows the active settings sources, including whether managed settings apply.
• /doctor checks installation health and invalid settings files, and proposes fixes that it asks before applying.
• /debug [issue] turns on debug logging for the session and has Claude diagnose the problem from the log.

Subdirectory CLAUDE.md files load on demand, not at session start, so they do not appear in the /context breakdown^[1].

If /context shows the file loaded but Claude still does not follow an instruction, the problem is probably how the instruction is written. Adherence drops when an instruction can be read several ways, when two files conflict, or when the file has grown so long that individual rules get less attention^[1].

CLAUDE.md and permissions do different jobs. CLAUDE.md tells Claude how the project works. Permissions and hooks enforce limits no matter what Claude decides. Use CLAUDE.md for "we do it this way here," and use permissions or hooks for anything that must never happen^[1].

Find the setting that overrides yours

Settings merge across managed, user, project and local scopes. Managed settings apply first when present. Among the rest, the closer scope wins, in the order local, project, then user. Command-line flags and environment variables form another override layer^[1]. When a setting seems to do nothing, another scope or an environment variable usually holds a different value^[1].

Run claude doctor in the terminal to print read-only installation and settings diagnostics without starting a session. Run /status inside a session to see which settings sources are active^[1].

Watch out for a few common mix-ups^[1]:

• ~/.claude.json holds app state and UI toggles. permissions, hooks and env belong in ~/.claude/settings.json. They are different files.
• settings.local.json overrides settings.json, and both override ~/.claude/settings.json.

MCP servers that do not show up

Run /mcp to see every configured server, its status, and whether you have approved it for this project^[1]. A server can be defined correctly and still provide no tools, for three common reasons^[1]:

• Project servers in .mcp.json need a one-time approval. If you dismissed the prompt, approve the server in /mcp.
• A server that fails to start shows as failed. Relative paths in command or args are a frequent cause, because they resolve against the directory you started Claude Code from, not against the location of .mcp.json. Use absolute paths for local scripts.
• A server that connects but lists zero tools needs a reconnect. Select Reconnect in /mcp. If the count stays at zero, run claude --debug=mcp and read the server's stderr in the debug log at ~/.claude/debug/<session-id>.txt^[1].

Project MCP configuration goes in .mcp.json at the repository root, with servers under the mcpServers key. It does not go inside .claude/. settings.json does not read an mcpServers key at all^[1].

Hooks that never fire

Run /hooks to list the hooks registered for the session, grouped by event. If a hook you wrote is missing, check these causes^[1]:

• Hooks go under the "hooks" key in a settings file. A hook in a standalone file is not loaded.
• A matcher written as a JSON array instead of a string makes Claude Code reject the entry as invalid. If the array sits under PreToolUse or PermissionRequest, none of that file's other hooks load either.
• A hook in a skill's frontmatter only appears after the skill has been invoked in the session.

If the hook shows up in /hooks but still does not fire, the matcher is the usual suspect^[1]:

• A matcher that lists several tools uses a single string with |, for example "Edit|Write". From v2.1.191 a comma works too. Earlier versions read the comma as a literal character, so "Edit,Write" matched nothing^[1].
• Matching is case-sensitive, and tool names are capitalized: Bash, Edit, Write, Read. A lowercase "bash" never matches^[1].
• A misspelled tool name matches nothing, so the hook fails silently^[1].

Edits to settings.json apply to the running session after a short delay, so you do not need to restart. If /hooks still shows the old definition a few seconds after you save, run /hooks again^[1]. To see every event and the exit code of each hook, start with claude --debug and trigger the tool call^[1].

Isolate the problem with safe mode

Start with claude --safe-mode. It launches with CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, output styles and keybindings all turned off. Authentication, model selection, built-in tools and permissions still work normally. Managed hooks and the organization's settings policy still apply^[1]. If the problem goes away in safe mode, one of the items you turned off is the cause. Check it with the matching command from above^[1].

To rule out your own settings entirely, use an empty folder and a fresh configuration directory:

mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty

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

--setting-sources user turns off project configuration such as .claude/settings.json, CLAUDE.md and .mcp.json. The first-run setup screens appear again, which confirms the clean directory is in use^[1]. If the problem disappears, copy your files back into the clean directory one at a time to find the one that brings it back. If it persists, the cause lies outside your user and project configuration^[1].

Common error messages

These messages come from the runtime error reference. They apply in the CLI, the Desktop app and cloud sessions^[2].

• **Not logged in · Please run /login.** No valid credential is available. Run /login. If you meant to authenticate with an environment variable, confirm that ANTHROPIC_API_KEY is set and exported in the shell where you launched claude^[2].
• **Invalid API key · Fix external API key.** The key from ANTHROPIC_API_KEY or from apiKeyHelper was rejected. A stale key can come from a .env file that direnv or a dotenv plugin loads. Check with env | grep ANTHROPIC in the same shell, or unset the variable and run /login^[2].
• **Your apiKeyHelper script is failing.** The helper exited with an error or timed out, printed nothing to stdout, or printed text besides the key. Claude Code retries the script up to two more times before it shows this message. Run the command yourself in the shell to reproduce the failure, and check /status, which shows the last failure^[2]. Running /login does not help, because the helper's output takes precedence over a saved login while the setting is present^[2]. A working helper prints only the key, as one token of printable ASCII up to 16,384 characters, and exits with code 0^[2].
• **API Error: 400 ... context_management: Extra inputs are not permitted.** A gateway probably dropped the anthropic-beta header that enables the field. Update Claude Code, forward the header at the gateway, or set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 before launching as a fallback^[2].
• **Model 'claude-opus-9' not found.** Claude Code could not confirm that model exists. Run /model with no argument to pick from the models your account can use, or use an alias such as sonnet^[2].
• **tools.N.custom.input_schema: JSON schema is invalid.** An MCP tool declares a schema the API refuses, and the whole request is rejected. The number is the tool's position in the list, not its name. Remove or disable the MCP server that declares it, and check each server's log^[2].

Where to go next

For the full list of configuration locations, read the .claude directory reference. For every setting and its scope, read the settings page and the settings reference. For login and install problems, read the installation and login troubleshooting page. These are all in the official Claude Code documentation^[1][2].