When claude doctor Listed Four Warnings, I Sorted Them by Cause Before Fixing Anything

I ran claude doctor in an isolated work environment just to check the state of Claude Code, and the last line said "4 warnings found."

My stomach dropped a little. Four warnings sounded like updates, auth, and who knows what else were all quietly broken.

They weren't. All four came from one cause. If I had fixed them in order, I would have done the same repair three times.

Here is how I sorted them, using the output exactly as it appeared.

The output, first

claude doctor is a read-only diagnostic. It prints install and settings health without starting a session. Mine looked like this, trimmed to the essentials:

Running: native (2.1.309)
Path: /usr/local/bin/claude
Config install method: not set
Auto-updates: enabled
Auto-update channel: latest
Last update attempt: none recorded
 
4 warnings found
- Native installation exists but ~/.local/bin is not in your PATH
- Running native installation but config install method is 'not set'
- claude command at $HOME/.local/bin/claude missing or broken
- claude command at $HOME/.local/bin/claude missing or broken

Warnings three and four are identical: same path, same message. The "4" was really three items.

One more thing worth noticing: the "Organization policy" and "Remote Control" lines say they couldn't be fetched when you aren't signed in. That isn't damage. It just means you haven't identified yourself yet, and those lines were not counted among the warnings.

Group the warnings by cause

One small table does the sorting.

That leaves two groups. And A is really a single thing: per the official setup page, the native installer puts a launcher at ~/.local/bin/claude, pointing into ~/.local/share/claude/versions/. When that location is missing, "not on PATH" and "launcher missing" show up together.

Ask whether it works right now

Before counting warnings, I checked whether anything was actually failing.

claude --version printed the version. claude update reported "Current version: 2.1.309," proceeded to check for updates, and attached the same PATH warning. Auto-updates stayed enabled.

So nothing was broken today. It was a state that could cause trouble later.

That gave me a line to hold: while it runs, don't rush; but unify the launch path before it stops running. On a warning day, that's the only preparation I do.

If claude instead returns "command not found," the order flips. Go to the "Fix your PATH" section of the official troubleshooting page first.

Three steps to fix group A

1. Add one line to your shell config (for zsh, ~/.zshrc):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

2. Open a new terminal, or run source ~/.zshrc.

3. Run claude doctor again.

For group B, doctor suggested claude install. As of writing, I haven't run it yet. It rebuilds the launcher, and I'd rather not replace a working path blindly. I'll add the result here once I have one.

What to check afterward

Beyond "did the warnings go away," I look at three places:

• Does the Path: line point where I expect?
• Are Auto-updates and Auto-update channel still the values I chose?
• Does Last update attempt show any failure?

If which -a claude lists more than one binary, two installs are overlapping. Follow the "Check for conflicting installations" section of the official docs and keep one. With two launch paths, an update can reach only one of them and leave the other stale.

Thirty seconds before touching anything

The lesson was simple: the number of warnings and the number of problems are different things.

• Collapse duplicated lines
• Separate sign-in-only info lines from warnings
• Check whether it runs, group by group

After that, the repair took two or three moves. Fixing "four" things would have left me unsure which change had actually worked.

Today, paste your own claude doctor output somewhere and color it by cause. That's where I started.