← 5.16.1 →
1838 words Slides

5.2 The /doctor Command

Course: Claude Code - Essentials Section: Troubleshooting Basics Video Length: 2-5 minutes Presenter: Daniel Treasure Studio: Stormwind Studios

Opening Hook

"If there's one command you should bookmark, it's /doctor. It's like running a full system diagnostic on your Claude Code setup. In the next 2-3 minutes, you'll learn what it checks, what the output means, and when to use it. By the end of this video—and the Essentials course—you'll have everything you need to troubleshoot Claude Code like a pro."

Key Talking Points

1. What Is /doctor?

  • A built-in diagnostic tool — part of Claude Code since day one
  • Checks the health of your Claude Code installation and environment
  • Runs automatically when certain issues are detected
  • Can be invoked manually anytime with /doctor in a session
  • Saves hours of manual troubleshooting

2. What /doctor Actually Checks

  • Installation integrity
  • Is Claude Code properly installed?
  • Are all dependencies in place?

  • Can the binary be found and executed?

  • Authentication state

  • Are you logged in?
  • Is your authentication token valid?

  • Can Claude Code reach the auth servers?

  • Configuration validity

  • Are your settings files properly formatted (valid JSON)?
  • Are permission rules syntactically correct?

  • Are hooks and custom commands discoverable?

  • System connectivity

  • Can Claude Code reach api.anthropic.com?
  • Are proxy or firewall issues present?

  • Is your network configuration correct?

  • Model accessibility

  • Can Claude Code fetch the available models?
  • Is your Claude account plan active?

  • Are you able to make API calls?

  • Local environment

  • Do required tools exist? (Node.js, git, etc.)
  • Are you in a supported OS/architecture?
  • Are file permissions correct for settings files?

3. When to Use /doctor

Use it proactively: - After installing Claude Code for the first time - After upgrading to a new version - After changing system configuration (proxy, VPN, network) - Before filing a support ticket

Use it reactively: - When you see "command not found: claude" - When login fails repeatedly - When permissions keep getting denied - When you get cryptic error messages - When other troubleshooting steps haven't worked

4. Reading the Output

  • /doctor outputs clear, hierarchical feedback
  • Green checkmarks (✓) or "OK" — that system is working
  • Yellow warnings (⚠) — something might be wrong but not blocking

  • Red errors (✗) or "FAILED" — this is definitely broken and needs fixing

  • Organization:

  • Listed by category (Installation, Auth, Config, Network, etc.)
  • Each issue includes what failed and why
  • Suggests remediation steps (though you now know these from the last video)

Demo Plan

Part 1: Intro & Setup (30 seconds)

Goal: Show a working Claude Code session

  1. Terminal: Start Claude Code session bash cd ~/my-project claude
  2. Show the prompt ready for input
  3. Narrate: "Here's a healthy Claude Code session. But how do we know it's healthy?"

Part 2: Run /doctor (1 minute 30 seconds)

Goal: Show actual /doctor output with real output

  1. Type the command: /doctor

  2. Show output in sections (pause and narrate each):

  3. Installation Check ✓ Installation verified: /usr/local/bin/claude v0.1.2 ✓ Dependencies: Node.js 18.x found Narrate: "Good sign — Claude Code is installed and we've got Node.js."

  4. Authentication ✓ Logged in as: you@example.com ✓ Token valid until: March 15, 2026 Narrate: "We're authenticated and the token hasn't expired."

  5. Configuration ✓ ~/.claude/settings.json: Valid JSON ✓ Permissions rules: OK ✓ Hooks: None configured Narrate: "Settings look good. No syntax errors."

  6. Connectivity ✓ api.anthropic.com: Reachable ✓ Network latency: 45ms (normal) Narrate: "We can reach the servers, no proxy blocking."

  7. Model Access ✓ Claude Sonnet: Available ✓ Claude Opus: Available ✓ Account plan: Claude Pro Narrate: "Both models available, your subscription is active."

  8. Full summary: All systems operational. Claude Code is ready to use.

Part 3: Show a Failing Example (1 minute)

Goal: Demonstrate what /doctor output looks like with errors

Pre-record a session where: - Authentication has expired, OR - Network is blocked, OR - Settings JSON is malformed

  1. Show the problematic output: ``` ✓ Installation verified: /usr/local/bin/claude v0.1.2 ✓ Dependencies: Node.js 18.x found ✗ Logged in as: FAILED (token expired)

Recommended action: Run: claude /login ```

OR

``` ✗ api.anthropic.com: UNREACHABLE (timeout)

Possible causes: - Network connectivity issue - Proxy or firewall blocking - ISP DNS issue

Recommended actions: 1. Check network: ping google.com 2. Check if proxy in use: echo $HTTP_PROXY 3. Try different DNS or VPN ```

  1. Narrate the interpretation:
  2. "See the ✗? That's where the problem is. The output tells us what's wrong."
  3. "It even suggests fixes. Try those first."

Part 4: How to Act on /doctor Results (45 seconds)

Goal: Show the next steps after running /doctor

  1. Flowchart (on screen): ``` Run /doctor | ├─ All green? → You're ready to code | └─ Any red? →

    1. Read the "Recommended action"
    2. Follow the steps from video 5.1
    3. Run /doctor again
    4. If still broken → file a support ticket with /doctor output ```

  2. Terminal demo (optional):

  3. Show /doctor output getting piped to a file (for support) bash /doctor > doctor-output.txt
  4. Narrate: "You can save the output and send it to support. They'll understand exactly what's wrong."

Part 5: Wrap-Up & Bridge to Power User Course (30 seconds)

Goal: Conclude the Essentials course and set up the next level

  1. Recap on screen:
  2. Video 5.1: Four common issues (install, auth, permissions, context)

  3. Video 5.2: How to diagnose with /doctor

  4. Narrate the transition: "You've made it through the Essentials course. You know how to install, authenticate, work with code, manage permissions, and—most importantly—diagnose and fix problems. Now you're ready for the Power User course, where we'll dive into advanced workflows: custom commands, hooks, MCP integrations, session management, and how top developers use Claude Code every day. See you in Power User section."

Code Examples & Commands

Running Diagnostics

# In a Claude Code session, simply:
/doctor

# To save output for support:
/doctor > ~/claude-doctor-report.txt

# To get verbose diagnostic info (if available):
claude --debug

Common /doctor Scenarios

Scenario 1: All green

✓ Installation OK
✓ Authentication OK
✓ Configuration OK
✓ Connectivity OK
✓ Model access OK

All systems operational.

→ You're good to go!

Scenario 2: Auth token expired

✗ Logged in: FAILED (token expired)

Recommended action:
Run: claude /login

→ Do exactly that.

Scenario 3: Network blocked

✗ api.anthropic.com: UNREACHABLE
⚠ May indicate firewall/proxy issue

→ Check network or corporate IT.

Scenario 4: Configuration syntax error

✗ ~/.claude/settings.json: INVALID JSON
Parse error at line 12, column 5

Recommended action:
Check settings.json for commas, quotes, brackets

→ Fix the JSON (use a linter tool).

Gotchas & Tips

Interpreting /doctor Output

  1. Green doesn't mean "never has issues" — it's a point-in-time check
  2. Warnings (yellow) might be fine — read the details before panicking
  3. Multiple errors often have one root cause — fix the first one, re-run
  4. Network timeouts can be intermittent — run /doctor twice to confirm

Common Misreadings

  1. "Token expires in 30 days" is NOT an error — it's just informational
  2. "Proxy detected" is NOT a failure — it means the proxy is configured (usually correct)
  3. "Updated available" is a WARNING, not a FAILURE — your current version still works

Pro Tips

  1. Run /doctor before reporting bugs — include output with tickets
  2. Bookmark /doctor in your notes — you'll use it more than you think
  3. Share /doctor output with teammates — helps isolate if it's local or team-wide
  4. Use /doctor to debug settings JSON — it's the fastest syntax checker

When /doctor Can't Help

  • Bug in your application code — /doctor checks Claude Code, not your project
  • Business logic errors — /doctor diagnoses environment, not your code
  • Slow responses — might be model load, not environment (check claude.com status)
  • Permission denials you intentionally set — /doctor won't override your own rules

Lead-out

"That's the Essentials course. You've gone from zero to confident in Claude Code. You understand the interface, the core workflows, how to interact with your code, and—most importantly—how to diagnose and fix problems. The /doctor command is your safety net. If something feels wrong, run it. It'll point you in the right direction. Now you're ready for the Power User course, where we're going to show you how to work like the Claude Code team itself: custom commands, automation, MCP integrations, and team workflows. Thanks for learning with us, and we'll see you in the next level."

Reference URLs

Official Documentation: - CLI Reference (all commands): https://code.claude.com/docs/en/cli-reference - Quickstart & First Session: https://code.claude.com/docs/en/quickstart - Permissions System: https://code.claude.com/docs/en/permissions - Settings & Configuration: https://code.claude.com/docs/en/settings

Troubleshooting Resources: - Official Release Notes: https://support.claude.com/en/articles/12138966-release-notes - ClaudeLog Guide: https://claudelog.com/ - GitHub Issues (search your error): https://github.com/anthropics/claude-code/issues

Prep Reading

  1. CLI Reference (Skim section on /doctor if available): https://code.claude.com/docs/en/cli-reference
  2. Quickstart (Review common workflows): https://code.claude.com/docs/en/quickstart
  3. Best Practices (Context for production use): https://code.claude.com/docs/en/best-practices
  4. Recent Release Notes (See new features in latest version): https://github.com/anthropics/claude-code/releases

Production Notes

Recording Setup: - Terminal in full screen with high contrast - /doctor output clearly readable (larger font if needed) - Show both "healthy" and "unhealthy" examples - Use color coding or emphasis to highlight ✓ vs ✗

Demo Strategy: - Record /doctor output once in advance (no lag on video) - Show it slowly, pausing on each section - Use on-screen callouts or arrows to emphasize key lines - Make the "all green" example feel satisfying—it's a win

Script Notes: - Emphasize that /doctor is diagnostic, not prescriptive (it helps you understand but doesn't fix) - Normalize running /doctor before each session (like a pre-flight check) - Position it as the first step in any troubleshooting

Course Closing: - This is the final video of Essentials - Wrap up with gratitude and forward momentum - Preview what's coming in Power User course - Suggest viewers practice what they learned before advancing

Transitions to Power User Course: - Custom slash commands (/skills) - Hooks and automation - MCP (Model Context Protocol) integrations - Advanced session management - Team workflows and shared configurations

Notes for Course Producer

  • Video 5.2 is the capstone of Essentials — make it feel like a satisfying conclusion
  • Include real /doctor output — record it from an actual session for authenticity
  • Show both success and failure states — viewers need to see what "wrong" looks like
  • Keep it under 5 minutes — this is a concrete, operational video, not theoretical
  • Emphasize that /doctor is the emergency brake — when in doubt, run it first