This lesson is being recorded
Every video of this course is being uploaded to my YouTube channel. Subscribe so you do not miss it.
Bruno Ashford @brunoashfordSubscribeModule 2 · Lesson 2.6 · 13 min
When Setup Goes Wrong
Diagnose and fix the most common installation and login errors on your own.
Use ← → to move. The marker highlights text and the pencil draws on the slide; navigation locks while you annotate. Undo removes the last mark, Esc exits.
1Run the health check first
Before searching anything, run these two commands. The first proves Claude Code is installed. The second prints a read-only diagnosis of your installation and settings with suggested fixes.
claude --version
claude doctor2Fix 'command not found' or 'not recognized'
Claude is installed but your terminal cannot find it. On Mac with the default shell, add the install folder to your PATH with the command below, then open a new window. On Windows, use the two-line PowerShell fix in the troubleshooting guide.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc3Fix the wrong-terminal errors on Windows
'irm is not recognized' means you are in CMD: open PowerShell. 'The token && is not a valid statement separator' means you pasted the CMD command into PowerShell: use the PowerShell command instead.
4Fix login problems
If the browser does not open, press c to copy the login link. If login keeps failing, type /logout inside Claude Code, close it and start again with claude. A 403 error usually means the subscription is not active or your company account lacks the Claude Code role.
5Fix the hidden API key problem
If Claude says your organisation is disabled while your subscription is active, an old API key on your computer is overriding it. Remove it and start again. On Windows PowerShell, use Remove-Item Env:ANTHROPIC_API_KEY instead. Inside Claude Code, /status shows which login is active.
unset ANTHROPIC_API_KEY
claude6Ask Claude to help with anything else
Once Claude Code runs, it can help diagnose its own setup. Type /doctor inside a session, or ask in plain English.
I just installed you and something feels wrong: [describe what you see]. Check my setup, explain the cause in plain English, and propose a fix. Ask me before changing anything.Here is something most tutorials will not tell you: setup is where non-technical people quit. Not because the problem is hard, but because the error message looks frightening and nobody explained what it means. Almost every error you will see has a one-line cause and a one-line fix.
In this lesson we walk through the errors I see most often with owners, in the order you are likely to meet them. Keep the Setup Troubleshooting Guide open. The golden rule: read the error, find its exact words in the guide, apply the fix, open a new window.
Key points
- Run claude --version and claude doctor first.
- Not found or not recognized means a PATH issue.
- Most Windows errors are the wrong terminal.
- /logout then log in again fixes most login problems.
- An old ANTHROPIC_API_KEY can override your subscription.
Avoid
- Reinstalling five times instead of reading the error message.
- Forgetting to open a new terminal window after a fix.
- Installing with several methods at once, which creates conflicting versions.
- Treating a billing or account issue as an installation issue.
The clinic's practice manager hit two errors in a row: 'claude is not recognized' on Windows, then a 403 after login. The first was the PATH fix. The second turned out to be a lapsed card on the Pro subscription. Both were solved in under ten minutes with the guide, without calling an IT provider at $120 an hour.