The claude doctor Command — How to Diagnose Claude Code Problems

by

Something isn’t working with Claude Code and you’re not sure where to start. Before you go searching forums or reinstalling everything, there’s a built-in tool that does the diagnosis for you in about three seconds.

It’s called claude doctor, and this article shows you exactly how to use it and what to do with what it tells you.

This is part of our complete Claude Code Beginner’s Guide.

TL;DR

  • claude doctor is a built-in diagnostic command that checks your Claude Code installation, authentication, and network
  • Run it from your terminal outside of a Claude Code session
  • It prints a status report with green checkmarks for things that are fine and warnings or errors for things that aren’t
  • Each error type has a specific fix — this article covers all of them
  • It’s always the right first step when something with Claude Code isn’t working

What is claude doctor?

claude doctor is a diagnostic command built into Claude Code. When you run it, it inspects your installation and prints a structured status report — covering your version, authentication state, network connectivity, settings files, and tool availability.

Think of it like the “check engine” diagnostic tool mechanics plug into a car. The car’s computer knows what’s wrong; the tool just reads it out for you. claude doctor does the same thing: Claude Code already knows what’s healthy and what isn’t, and this command surfaces that information clearly.

You don’t need to be inside a Claude Code session to run it. You run it directly in your terminal.

How to Run claude doctor

Open your terminal and type:


# Run the Claude Code diagnostic tool
claude doctor

Press Enter. The command takes two to five seconds to run, then prints its report. That’s all there is to it.

⚠️ Warning: Don’t run claude doctor while you’re inside an active Claude Code session. Exit first (type /exit or press Ctrl+C), then run it in your regular terminal.

How to Read the Output

The report is divided into sections. Each line has a status indicator:

  • ✓ (green checkmark)** — this item is healthy, no action needed
  • ⚠ (yellow warning)** — something is suboptimal but not broken
  • ✗ (red cross)** — something is wrong and needs fixing

A fully healthy install looks like this:


✓ Claude Code version: 2.1.211
✓ Installation: Native installer
✓ Auto-updates: Enabled (latest channel)
✓ Network: Connected
✓ Auth: Authenticated (pro plan)
✓ Shell integration: bash, zsh
✓ Tools: ripgrep available
✓ Settings: ~/.claude/settings.json (valid)

If you see all checkmarks, Claude Code is healthy and the problem you’re experiencing is likely something else — a project-level issue or a usage question rather than an installation problem.

If you see warnings or errors, read on.

What Each Status Line Means

Claude Code version


✓ Claude Code version: 2.1.211

Shows your installed version. If this line shows a very old version alongside an auto-update warning, your auto-updater may have stopped working. See the How to Update Claude Code guide for manual update instructions.

Installation


✓ Installation: Native installer

Shows how Claude Code was installed — native installer, Homebrew, npm, apt, etc. This matters because update commands differ per install method.

If this shows npm (legacy), you’re on the old installation method. Claude Code still works, but consider migrating to the native installer for automatic updates.

Auto-updates


✓ Auto-updates: Enabled (latest channel)
⚠ Auto-updates: Disabled

The warning means auto-updates are turned off — either intentionally (via DISABLE_AUTOUPDATER in settings) or because something is blocking them. If you didn’t disable it on purpose, check your ~/.claude/settings.json file for a DISABLE_AUTOUPDATER entry and remove it.

Network


✓ Network: Connected
✗ Network: Cannot reach api.anthropic.com

The error means Claude Code can’t connect to Anthropic’s servers — the ones it needs to actually run. This is almost always caused by one of:

  • A VPN blocking the connection
  • A corporate firewall that hasn’t allowlisted api.anthropic.com
  • A proxy configuration issue

Fix: Disable your VPN and run claude doctor again. If the network check passes without the VPN, the VPN is the cause. If you need the VPN for work, ask your IT team to allowlist api.anthropic.com and claude.ai.

Auth


✓ Auth: Authenticated (pro plan)
✗ Auth: Not authenticated
⚠ Auth: Authenticated (free plan — Claude Code not included)

Not authenticated means you haven’t logged in, or your session expired. Fix: run claude auth login.

Free plan warning means you’re logged in but your account doesn’t include Claude Code. You need to upgrade to Pro or higher at claude.ai/upgrade, then run claude auth logout and claude auth login to refresh.

For detailed login troubleshooting, see Claude Code Login Problems — How to Fix Them.

Shell integration


✓ Shell integration: bash, zsh
⚠ Shell integration: Not detected

Not detected means the claude command might not be in your shell’s PATH — so you may get command not found when trying to run Claude Code in new terminal windows.

Fix on Mac/Linux:


# Add ~/.local/bin to your PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Use ~/.bashrc instead if you’re using Bash.

Fix on Windows (PowerShell):


# Add Claude Code to your PATH permanently
$env:PATH += ";$env:USERPROFILE\.local\bin"
[System.Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")

Tools: ripgrep


✓ Tools: ripgrep available
⚠ Tools: ripgrep not found (using slower fallback)

ripgrep is a fast file-search tool that Claude Code uses to search through your codebase efficiently. If it’s not found, Claude Code falls back to a slower built-in search. It still works, just slower on large codebases.

Fix on Mac:


# Install ripgrep via Homebrew
brew install ripgrep

Fix on Ubuntu/Debian:


# Install ripgrep via apt
sudo apt install ripgrep

Fix on Alpine Linux (where this is more common):


# Install ripgrep on Alpine
apk add ripgrep

Settings file


✓ Settings: ~/.claude/settings.json (valid)
⚠ Settings: ~/.claude/settings.json (invalid JSON)
✗ Settings: Missing

Invalid JSON means your settings file has a syntax error — usually a missing comma, an extra bracket, or a broken edit. Fix it by opening the file and correcting the JSON:


# Open your settings file to inspect and fix it
nano ~/.claude/settings.json

Valid JSON requires every key-value pair except the last to end with a comma, all strings in double quotes, and matching curly braces. If you’re not sure what’s wrong, you can paste the contents into any JSON validator online.

Missing means the settings file doesn’t exist yet. This is normal for a fresh install — Claude Code creates it on first use. If you’re seeing this after having configured things before, it may have been accidentally deleted. Claude Code will recreate it with defaults, so you can just run claude and re-apply your settings.

Running claude doctor on a Server

If you’re running Claude Code on a remote Linux server (via SSH), claude doctor works the same way — just run it in your SSH session. The one difference is the network check: make sure you test from the server itself, not your local machine, since the server’s network configuration is what matters.

When claude doctor Passes but Claude Code Still Doesn’t Work

A clean claude doctor report means the installation and connectivity are healthy. If things still aren’t working, the issue is probably one of:

  • Wrong folder:** You’re running claude from a folder without a project. Navigate into your project directory first.
  • Rate limit:** You’ve hit your plan’s usage limit. Claude Code will tell you in the session — wait for the reset (typically around 5 hours) or upgrade your plan.
  • Model issue:** Occasionally Anthropic has service incidents. Check status.anthropic.com to see if there’s an outage.
  • Session problem:** Close the current session and start a new one with claude.

Key Takeaways

  • Run claude doctor in your terminal (outside a session) whenever something with Claude Code isn’t working
  • Green checkmarks mean healthy; yellow warnings are non-critical; red crosses need fixing
  • Network errors** are almost always VPN or firewall related — test without your VPN first
  • Auth errors** mean you need to log in or upgrade your plan
  • Shell integration warnings** mean claude may not be in your PATH — fix with an export line in your shell profile
  • ripgrep missing** just means slower file search — install it for better performance on large codebases
  • A clean claude doctor report with problems still occurring points to rate limits, wrong folder, or a service incident

Next Steps

Return to the Claude Code Beginner’s Guide for the full learning path.