Field Guide
ModulesPhase 4: Enterprise

16. Troubleshooting

/doctor/status/debug
The 30-second answer

"Start by finding out what is actually in effect, not what you think is configured. /status shows the version, account, live credential, gateway address and which settings sources loaded. /doctor runs a setup checkup and offers fixes; if Claude Code won't even start, claude doctor does a read-only version from the shell. For behavior that's wrong mid-session, /debug turns on logging and has Claude read it; for startup, hooks or MCP, launch with claude --debug. If a customization might be the cause, claude --safe-mode turns them all off. When it's a real bug, /bug sends the report with the user's consent."

The first sentence is the habit that separates a support engineer from someone guessing.

Say it yourself first, then compare.
See it

8 pictures, in order.

Use the arrow keys or the dots. Tap a picture to see it full size.

Triage: symptom to command1 of 8
Know it

The facts someone can check.

Triage table
Symptom Run
claude won't start claude doctor from the shell
Something in the setup feels off /doctor
Which account, settings or gateway is live? /status
Claude ignores an instruction /context
Wrong behavior mid-session /debug [description]
Startup, hooks or MCP misbehave claude --debug, or --debug=mcp
A hook never fires /hooks, then claude --debug
An MCP server has no tools /mcp
Memory keeps climbing /heapdump
Could it be a customization? claude --safe-mode
Did an update change this? /release-notes
It's a real bug /bug or /feedback
/doctor
  • A bundled skill that reports first, proposes fixes, and applies them only after you confirm. Alias /checkup.
  • Checks five areas: installation health, extensions (unused skills, MCP servers and plugins against their context cost, slow hooks), CLAUDE.md files, permissions, and on paid plans the changes /usage recommends over the last 7 days (v2.1.305 or later). It also estimates what your skill listing costs in context.
  • claude doctor in the shell is the read-only cousin: install health, settings validation and Remote Control eligibility, without starting a session. It's also where dropped managed-settings entries and the Organization policy line show up.
  • /doctor prompt-audit [path] audits CLAUDE.md, skills and configuration for stale or conflicting instructions instead (v2.1.283 or later). Module 1 uses it.
  • Admins can hide it with DISABLE_DOCTOR_COMMAND or a skillOverrides entry.
/status
  • Opens Settings on the Status tab: version, model, account, connectivity. It works while Claude is responding.
  • Setting sources names the files that loaded; a managed policy shows as Enterprise managed settings (file) or similar. Skipped sources names a policy that reached the machine but lost.
  • Anthropic base URL appears only when a gateway is set. The Auth token or API key line names the live credential; a Login method line naming a claude.ai account means no gateway credential is in use.
  • A Login row reads expired before requests start failing (v2.1.210 or later). On Bedrock it shows the resolved region and where it came from.
/debug and claude --debug
/debug [description] claude --debug
Starts logging From the moment you run it From launch
Best for Behavior that goes wrong mid-session Startup, hook matching, MCP server stderr
Extras Claude reads the log and diagnoses --debug=mcp,startup filters; --debug-file <path>; DEBUG=1
  • The log lands at ~/.claude/debug/<session-id>.txt, or the file path in CLAUDE_CODE_DEBUG_LOGS_DIR.
  • CLAUDE_CODE_DEBUG_LOG_LEVEL: verbose, debug (default), info, warn, error.
  • In the log, [3P telemetry] lines are your own OpenTelemetry exporter failing; [Anthropic telemetry] lines are Anthropic's and not your problem.
  • --verbose is not a log. It shows full turn-by-turn output in the terminal.
Error classes
Family Example First move
Server API Error: 500, Repeated 529 Overloaded Already retried. Check status.claude.com
Usage limits "You've hit your session limit" Shared across models; /usage-credits or wait
Spend limits "You've hit your monthly spend limit" An admin raises it
Authentication Not logged in, Invalid API key /status; look for a stray ANTHROPIC_API_KEY
Network Connection refused, ENOTFOUND Wrong base URL, VPN or firewall
TLS SSL certificate verification failed NODE_EXTRA_CA_CERTS
Request 400 Extra inputs are not permitted Behind a gateway, CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Model "There's an issue with the selected model" /model, then find the stale model ID
No error, worse answers /model, /effort, /context, then /rewind

Claude Code retries transient failures up to 10 times with backoff before you see anything. CLAUDE_CODE_MAX_RETRIES defaults to 10 and caps at 15.

Reporting it
  • /bug (alias /share) and /feedback open the same dialog. You choose how much history to include (this session by default, or other sessions from the same project over the last 24 hours or 7 days) and confirm on a consent screen.
  • Signed in to Anthropic on a first-party connection, the report goes to Anthropic and transcripts are kept 5 years. On Bedrock, Agent Platform, Foundry or with no Anthropic credentials, it's written to ~/.claude/feedback-bundles/ with known keys redacted, for you to forward. DISABLE_FEEDBACK_COMMAND=1 turns it off.
  • /heapdump is hidden from the menu. It writes a .heapsnapshot (contains your conversation and credentials, never share it) and a -diagnostics.json (statistics only, attach this one) to ~/Desktop. A warning appears when the heap passes 2.5 GB.
  • /release-notes opens a version picker over the changelog. The notes show in your transcript but don't enter Claude's context. It fetches from raw.githubusercontent.com.
Bisect the configuration
  1. claude --safe-mode: turns off CLAUDE.md, skills, plugins, hooks, MCP servers, custom commands and agents, output styles, keybindings, the status line and auto memory. Managed policy still applies.
  2. A clean config directory: from an empty folder, CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user.
  3. Add files back one launch at a time until the problem returns.
  4. Still broken with nothing of yours loaded? It's managed settings or an environment variable: check /status and the shell.

Common causes worth checking first: a hook matcher written as an array or in lowercase, permissions put in ~/.claude.json instead of ~/.claude/settings.json, .mcp.json inside .claude/ instead of the repo root, and a skill saved as a file instead of a folder with SKILL.md.

The architect's point

Troubleshooting at scale is a design problem, not a heroics problem. Each failure you understand once should become a check that runs on its own: a note where the next session will read it, a hook that warns, a diagnostic with a negative test. A support model that depends on one person remembering is the same anti-pattern as a rule that only lives in CLAUDE.md.

Quiz

Answer out loud, then flip the card.

Mark each one honestly. Cards you miss stay flagged for review, in this browser.

0 of 8 right
Question 1

A user says "Claude Code won't even open." What do you ask them to run?

claude doctor from their shell. It prints read-only installation and settings diagnostics without starting a session, including settings files that fail validation. Note that a managed settings file that isn't valid JSON makes Claude Code refuse to start, so ask whether IT pushed anything recently. Once it starts, /doctor can offer fixes.

Question 2

IT pushed a policy that blocks reading .env files, and a developer says it isn't working. What's your sequence?

/status on their machine: does Setting sources show Enterprise managed settings, and from which source? If missing, the policy didn't land. If a different source is named, a higher-priority one won and Skipped sources will list yours. Then claude doctor for entries dropped as invalid. Then /permissions to see the resolved deny rules.

Question 3

An MCP server shows as connected but has zero tools. What next?

Select Reconnect in /mcp. If it stays at zero, restart with claude --debug=mcp and read the server's stderr in ~/.claude/debug/<session-id>.txt. Relative paths in command or args are a frequent cause, since they resolve from the launch directory.

Question 4

A developer ran /debug after the problem happened, and the log shows nothing useful. Why?

/debug starts logging from the moment it runs, so earlier events aren't in the log. Reproduce the problem after running it, or for startup, hook or MCP issues, restart with claude --debug so logging starts at launch.

Question 5

A customer's security team asks what /heapdump captures before they allow it.

Two files on the Desktop. The .heapsnapshot holds every string in the process, including the conversation and credentials, so it should never leave the machine. The -diagnostics.json holds only memory statistics and is the one to attach to a report. The command is hidden from the menu and only runs when typed in full.

Question 6

A team on Bedrock wants to report a bug to Anthropic. What happens when they run /feedback?

Nothing is sent. On Bedrock, Agent Platform, Foundry or with no Anthropic credentials, /feedback writes a local archive under ~/.claude/feedback-bundles/ with known keys redacted. They review it and send it to their Anthropic account representative or attach it to a support request.

Question 7

Behind a LiteLLM gateway, every request fails with 400 "Extra inputs are not permitted." What is it?

The gateway forwards to an upstream that rejects request fields Claude Code sends to Anthropic-format endpoints. Set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1, which suppresses most pre-release fields. If one still gets through, set the matching CLAUDE_CODE_USE_* provider variable so Claude Code sends only what that provider accepts.

Question 8

Claude seems worse today, with no error. What do you check before blaming the model?

/model (a stale choice or ANTHROPIC_MODEL may have you on a smaller model), /effort, and /context for a nearly full window or large CLAUDE.md and MCP definitions. Then /rewind to before the bad turn and rephrase, instead of correcting in the thread. If it's still off, /feedback with what you expected versus what you got.

Traps

Wrong answers that sound right.

Before you tap, say why each one is wrong.

Try it

Three moves in a fresh project.

Facts checked against code.claude.com/docs/en/ pages commands, skills, cli-reference, troubleshooting, debug-your-config, errors, data-usage, env-vars, llm-gateway-connect, managed-settings and monitoring-usage on 2026-10-25. Claude Code ships fast: confirm anything that matters against the official docs.