Skip to main content

​
claude doctor

The doctor command runs diagnostic checks against your Claude Code installation and reports any problems it finds. 
claude doctor
The command is enabled by default. Set DISABLE_DOCTOR_COMMAND=1 to hide it from the CLI.

​
Debug mode

Pass --debug to any Claude Code command to enable verbose output, including API request/response details, hook execution logs, and internal diagnostics. 
claude --debug
claude --debug "explain this file"
Debug output includes structured timing information for startup phases (MDM load, plugin hook registration, etc.) and full hook stdout/stderr.

​
Log files

Log typeLocation
Debug logs~/.claude/debug/
Latest debug log~/.claude/debug/latest
Session transcripts~/.claude/projects/
Error logs~/.claude/errors/ (internal builds only)
Errors are also kept in an in-memory ring buffer (last 100) for the current session. They are written to debug logs and, on internal builds, to the errors directory. To stream debug logs while Claude Code is running: 
tail -f ~/.claude/debug/latest

​
Checking the version

claude version
claude --version

​
Common errors and fixes

Symptoms: 401 Unauthorized, 403 Forbidden, or messages about an invalid API key.Fixes:
  • Verify ANTHROPIC_API_KEY is set correctly in your environment.
  • If using OAuth, run claude and follow the login prompt, or check that your OAuth token has not expired.
  • If using apiKeyHelper, confirm the script is executable and outputs a valid key on stdout.
  • On Bedrock or Vertex, check that CLAUDE_CODE_USE_BEDROCK / CLAUDE_CODE_USE_VERTEX is set and that your cloud credentials are valid.
  • Run claude doctor to verify the authentication configuration.
Symptoms: Messages beginning with phrases like "You've hit your", "You've used", "You're close to", or "You're out of extra usage".Fixes:
  • Wait for the reset time shown in the message.
  • If you are on a usage-based plan, consider upgrading or purchasing extra usage.
  • For team deployments, check whether organization-level policy limits are restricting access (see the enterprise docs).
  • Claude.ai Team and Enterprise subscribers can contact support if limits are unexpectedly low.
Symptoms: Errors about the context being too long, or Claude stops mid-task with a context-related message.Fixes:
  • Use /compact or /clear to start a fresh context.
  • Break large tasks into smaller sub-tasks so each fits within the context window.
  • Consider using the Explore built-in agent for read-only investigation—it runs in its own context and returns a summary.
  • Reduce the number of files loaded via @ mentions or CLAUDE.md auto-inclusions.
Symptoms: Timeouts, ECONNREFUSED, SSL certificate errors, or ERR_NETWORK.Fixes:
  • Set HTTPS_PROXY if outbound traffic must go through a corporate proxy.
  • If you receive SSL certificate errors, ensure the proxy CA certificate is trusted by the system. In CCR environments, the CA is merged automatically.
  • Set CLAUDE_CODE_CLIENT_CERT to a PEM client certificate if your proxy requires mutual TLS.
  • Check that anthropic.com is reachable from your network; some firewalls block it.
  • Run claude --debug and inspect the request/response log for detailed network diagnostics.
Symptoms: Syntax errors on startup, require is not defined, or errors about unsupported ES features.Fixes:
  • Claude Code requires a recent Node.js version. Run node --version and compare against the minimum version in the release notes.
  • Use a version manager (nvm, fnm, Volta) to switch to a supported version.
  • If Claude Code ships as a self-contained binary, ensure you are running the binary and not an older globally installed version (which claude).
Symptoms: Hooks show errors in the spinner, operations are unexpectedly blocked, or hooks do not appear to run.Fixes:
  • Run claude --debug to see full hook stdout/stderr.
  • Check the hook configuration with /hooks.
  • A hook command that exits with code 2 blocks the operation and surfaces stderr to Claude—inspect that output for the block reason.
  • If allowManagedHooksOnly is set in managed settings, user/project/local hooks are silently disabled. Contact your administrator.
  • Verify the hook command is executable and the path is correct.

​
Performance tips

1

Use bare mode

Pass --bare to skip all hooks and reduce startup overhead. Bare mode is useful for scripting and non-interactive use.
claude --bare -p "summarize this file"
2

Disable background tasks

If background agent tasks cause unexpected CPU usage, set:
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1
3

Reduce hook complexity

Hooks that run on every PreToolUse event add latency to every tool call. Use matcher and if conditions to narrow hook execution to only the events that need them.

​
Submitting feedback

The /feedback command (also aliased as /bug) opens a feedback form in your browser to report bugs or suggestions. 
/feedback
/bug
The command is not available on Bedrock, Vertex, or Foundry deployments, or when DISABLE_FEEDBACK_COMMAND=1 / DISABLE_BUG_COMMAND=1 is set.

Build docs developers (and LLMs) love

Get started for freeTalk to us