Text of code.claude.com › docs › en › debug-your-config as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Debug your configuration - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. When Claude ignores an instruction or a feature you configured doesn’t appear, the cause is usually that the file didn’t load, it loaded from a different location than you expected, or another file overrode it.

This guide shows how to inspect what Claude Code actually loaded so you can narrow down which applies. For installation, authentication, and connectivity problems, see Troubleshoot installation and login instead. See what loaded into context The /context command shows everything occupying the context window for the current session. It breaks this down by category: system prompt, system tools, MCP tools, custom subagents with the source each loaded from, memory files, skills, and conversation messages.

Run it first to confirm whether your CLAUDE.md , rules, or skill descriptions are present at all. The skills section in /context also includes bundled skills , which /skills doesn’t list. In fullscreen mode , /context collapses the per-item breakdown, so run /context all to expand it. For detail on a specific category, follow up with the dedicated command: Command Shows /memory Memory file locations across user and project scopes with the option to open each in your editor, plus access to the auto memory folder and the auto memory toggle /skills Available skills from project, user, and plugin sources /hooks Active hook configurations /mcp Connected MCP servers and their status /permissions Resolved allow and deny rules currently in effect /doctor Setup checkup: installation health, invalid settings files, unused extensions, duplicate subagent names in the same directory, and checked-in CLAUDE.md content Claude can derive from the codebase, with proposed fixes /debug [issue] Enables debug logging for the session and prompts Claude to diagnose using the log output and settings paths /status Active settings sources, including whether managed settings are in effect If a memory file is missing from the /context breakdown, check its location against how CLAUDE.md files load .

Subdirectory CLAUDE.md files load on demand rather than at session start, so they don’t appear in that breakdown. If /context confirms the file loaded but Claude still isn’t following a particular instruction, the issue is likely how the instruction is written rather than whether it loaded. CLAUDE.md works well for the kinds of guidance you’d give a new teammate, such as project conventions, build commands, and where files belong.

Adherence drops when an instruction is vague enough to interpret multiple ways, when two files give conflicting direction, or when the file has grown long enough that individual rules get less attention. Write effective instructions covers the specificity, size, and structure patterns that keep adherence high. CLAUDE.md and permissions solve different problems. CLAUDE.md tells Claude how your project works so it makes good decisions.

Permissions and hooks enforce limits regardless of what Claude decides. Use CLAUDE.md for “we do it this way here.” Use permissions or hooks for security boundaries and anything that must never happen, where you need a guarantee instead of guidance. Check resolved settings Settings merge across managed, user, project, and local scopes. Managed settings apply first when present. Among the rest, the closer scope overrides the broader one in the order local, then project, then user.

Some settings can also be set by command-line flags or environment variables , which act as another override layer. When a setting doesn’t seem to apply, the value you set is usually being overridden by another scope or an environment variable. To find invalid settings files, run claude doctor from your terminal. It prints read-only installation and settings diagnostics without starting a session. For a full checkup that also proposes fixes and asks before applying them, run /doctor inside a session.

Run /status to see which settings sources are active, including whether managed settings are in effect. To understand which scope Claude Code uses for a given key, see Settings precedence . Check MCP servers Run /mcp to see your servers and their connection status. A server can be defined correctly but still not provide tools for a few common reasons: Project-scoped servers in .mcp.json require a one-time approval. If you dismissed the prompt, the server stays disabled.

To see the prompt again, run claude mcp reset-project-choices and restart Claude Code. It asks again for every project server. A server that fails to start shows as failed in /mcp . Relative file paths in command or args are a frequent cause, since they resolve against the directory you launched Claude Code from rather than the location of .mcp.json . A server that shows as connected but lists zero tools has started successfully but isn’t returning a tool list.

Select Reconnect from /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 . For configuration locations and scope rules, see MCP . Check hooks Run /hooks to list every hook registered for the current session, grouped by event. If a hook you defined doesn’t appear, Claude Code didn’t load it. Check for these causes: The hook is defined in a standalone file.

Hooks go under the "hooks" key in a settings file . The matcher value is an array instead of a single string. Claude Code lists the entry as an invalid setting when you start an interactive session and in claude doctor . If the array is under PreToolUse or PermissionRequest , none of that file’s other hooks load either. The hook is in a skill’s frontmatter, and neither you nor Claude has invoked the skill yet in this session.

Invoke it or ask Claude to, then run /hooks again. If the hook still doesn’t appear, check for other causes, such as frontmatter that didn’t parse or one of the limits on skill hooks . If the hook appears but doesn’t fire, the matcher is the usual cause. Check it for these mistakes: The matcher field is a single string that uses | to match multiple tool names, for example "Edit|Write" . A , separator is equivalent, so "Edit,Write" matches the same tools.

Before v2.1.191, a comma fell through to regex evaluation and the matcher never matched, so use | if you aren’t on v2.1.191 yet. A misspelled tool name produces a matcher that matches nothing, so the hook fails silently. When you edit settings.json , the change takes effect in the running session after a brief file-stability delay, even if you create the file or the project’s .claude/ folder itself after the session started.

You don’t need to restart. Before v2.1.257, Claude Code didn’t detect edits in a .claude/ folder created after the session started. If /hooks still shows the old definition a few seconds after you save, run /hooks again to refresh the view. If /hooks shows the hook but it still doesn’t fire, the next step is to watch hook evaluation live. Start a session with claude --debug and trigger the tool call. See Debug hooks for the log format and hooks troubleshooting for common failure patterns.

Test against a clean configuration Start with claude --safe-mode , which launches a session with your customizations disabled, including: CLAUDE.md Skills, plugins, and hooks MCP servers Custom commands and agents Custom output styles Custom keybindings Authentication, model selection, built-in tools, and permissions work normally. If the problem disappears in safe mode, you’ve narrowed the cause to one of the items you turned off.

To find it, use the check for that item, such as See what loaded into context , Check MCP servers , or Check hooks . Safe mode still applies managed hooks and settings policy from your organization. Mana

The rest of this page is on the live site.