.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
After a year of running Claude Code on Ubuntu 24.04 servers, a Mac and one reluctant Windows laptop, I've noticed the same handful of errors account for nearly every support thread, and most have boring fixes. This page is the catalog: each error as I've seen it, the cause and the fix, with a verification step so you know it worked. A few diagnostic commands come up over and over, so learn them once. claude doctor from the shell reports install health, while /status inside a session shows which credential and account you're really using. And claude -p "test" --bare runs a prompt with hooks, plugins, MCP servers and memory all skipped, which isolates your config from the CLI itself in one move.
claude: command not found
The exact wording varies by platform: zsh: command not found: claude on macOS, bash: claude: command not found on Linux, 'claude' is not recognized as an internal or external command in CMD and The term 'claude' is not recognized as the name of a cmdlet in PowerShell. All four mean the same thing. The installer put the binary at ~/.local/bin/claude (Windows: %USERPROFILE%\.local\bin\claude.exe) and that directory isn't on your PATH, or your current terminal predates the install and kept its old PATH.
Try a new terminal first; that alone fixes the fresh-install case. If it persists on Linux or macOS:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
claude --versionZsh users append to ~/.zshrc instead. On Windows, add %USERPROFILE%\.local\bin to your user PATH through Environment Variables and reopen the terminal; the PowerShell one-liner for it is in my guide to running Claude Code on Windows. One trap from the official docs worth repeating: the VS Code extension bundles its own private CLI copy and never touches your PATH, so having the extension doesn't mean claude exists in a terminal. Install the standalone CLI separately, which for Linux users I walked through in installing Claude Code on Ubuntu.
npm EACCES errors after installing with sudo
If you installed with sudo npm install -g @anthropic-ai/claude-code, you now own the consequences: root-owned directories that later updates and normal runs can't write to, surfacing as EACCES permission errors. Anthropic warns against sudo installs explicitly. The fix I'd pick every time is abandoning the npm route rather than repairing it:
sudo npm uninstall -g @anthropic-ai/claude-code
curl -fsSL https://claude.ai/install.sh | bashThe native installer runs as your user, needs no Node.js and auto-updates itself. If you have a reason to stay on npm (a locked-down CI image, say), repoint npm's prefix to a user-owned directory with npm config set prefix ~/.npm-global, add its bin to PATH and reinstall without sudo. Verify either way with claude doctor, which reports the install method and flags permission problems.
API Error: 400 This organization has been disabled
You have an active Pro or Max subscription and you logged in with /login, yet the CLI still throws a 400 with "This organization has been disabled". The cause is almost always an ANTHROPIC_API_KEY environment variable left over from an old project or employer. Once approved, that key takes precedence over your subscription OAuth login, and in -p mode it's used without asking. Claude Code is faithfully billing an organization that no longer exists.
unset ANTHROPIC_API_KEY
claudeThen hunt down the export ANTHROPIC_API_KEY=... line in ~/.bashrc, ~/.zshrc or ~/.profile and delete it, or the error returns with your next shell. Windows users check $PROFILE and the user environment variables. Confirm with /status: it should show your subscription account and email, not an API key. The same stale-key mechanism explains most "wrong account" and surprise-billing reports too, so I check env | grep ANTHROPIC before believing any auth error at face value.
403 Forbidden after login
The full string is API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}, and it lands after a login that seemed to succeed. Which fix applies depends on the account type. On Pro and Max, confirm the subscription is active in your claude.ai settings. Console (API) users need the "Claude Code" or "Developer" role, which an admin assigns under Settings, then Members, in the Console; without it, login works and every request afterwards is refused. On Team and Enterprise plans the workspace admin controls who gets Claude Code, so this error right after your org rolls it out means your seat or role isn't enabled yet. Corporate proxies produce the same 403 by mangling requests, which the official install and login troubleshooting page covers alongside the certificate side of that mess.
Verification is the same in every case: /status shows the login method and organization, and a short prompt in a fresh session confirms requests flow.
/login won't open a browser on a headless server
Not an error string, but it strands more VPS users than any real bug. /login wants to open a browser for OAuth, and over SSH there's no browser to open. The flow handles this, it just doesn't advertise it: press c at the login prompt to copy the OAuth URL, open that URL in the browser on your laptop and sign in. The page then hands you a code to paste back into the terminal. If pasting into the interactive prompt does nothing (some terminals swallow it), claude auth login reads the code from standard input instead. WSL2 users have a third option: point the BROWSER variable at the Windows Chrome executable and the redirect works locally.
I run Claude Code on remote boxes constantly and covered the setup in running Claude Code on a VPS. If you'd rather not do the install and PATH dance at all, LumaDock's Claude Code VPS hosting deploys the one-click template on Ubuntu with the CLI preinstalled, leaving the copy-the-URL login as the only setup step left.
Error editing file
Mid-session, Claude tries to apply a change and the tool call comes back with Error editing file, sometimes repeatedly on the same file. There's a dedicated GitHub issue on it, plus a pile of duplicates. From the reports, two causes dominate. First, the edit tool matches exact text, so any drift between what Claude read and what's on disk (whitespace, indentation, a formatter that ran in between) makes the match fail. Second, the file legitimately changed since Claude last read it: your editor auto-saved, a watcher rebuilt it or a PostToolUse formatting hook rewrote it, and the tool refuses to edit stale state. Windows adds CRLF line endings as a third suspect in community writeups, though I haven't seen Anthropic confirm that one.
The fix that works most reliably is also the dumbest: tell Claude "read the file again, then make the edit". A fresh read resyncs its copy with the disk. If a formatting hook keeps rewriting files behind Claude's back, either move the formatter to run once at the end or accept the occasional re-read; my Claude Code hooks guide covers sequencing hooks so they don't fight the edit loop. Repeated failures on files Claude just read, with none of the above in play, are bug territory and worth a report with the session log.
Search tool not finding files
When the Search tool, @file mentions or skill discovery come up empty in a project you know has matches, the bundled ripgrep binary may not run on your system. The documented fix is switching to your platform's ripgrep and telling Claude Code to use it. On Ubuntu:
sudo apt install ripgrepThen set the switch in the env block of settings.json:
{
"env": {
"USE_BUILTIN_RIPGREP": "0"
}
}Run claude doctor afterwards and check the Search line: it should show your system ripgrep's path instead of "OK (bundled)". One more search gotcha from the runtime troubleshooting doc: on WSL, projects living under /mnt/c/ search slowly and return fewer results than expected because of cross-filesystem penalties. Moving the project into the Linux filesystem under /home/ fixes both.
Update errors and auto-update
The native install auto-updates by default. Everything else doesn't: Homebrew needs brew upgrade claude-code, WinGet needs winget upgrade Anthropic.ClaudeCode and the apt/dnf repos wait for your package manager. Whatever the method, claude update triggers a manual check and claude --version confirms the result. Two channels exist, latest and stable (about a week behind), switchable via /config or the autoUpdatesChannel setting. To stop auto-updates entirely, put DISABLE_AUTOUPDATER=1 in the env block of settings.json; I do this on production servers where I want updates to happen on my schedule, and nowhere else.
The connection dropped while downloading the update
This one is transient. The download lost its connection partway; retry claude update once the network settles. Seeing it repeatedly on a stable connection points at a proxy or firewall interfering with downloads.claude.ai, which is the same host the installer uses, so the connectivity checks from the install docs apply.
npm error code ENOTEMPTY during update or reinstall
Exclusive to npm installs. An interrupted earlier update left a directory npm now can't move aside. Delete the directory named in the npm error path line plus any .claude-code-* leftovers next to it, then reinstall:
rm -rf "$(npm root -g)/@anthropic-ai/claude-code"
rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*
npm install -g @anthropic-ai/claude-codeKeeping Claude Code updated: CVE-2026-54316
A short story for anyone tempted to pin an old version forever. Claude Code's WebFetch tool shipped with huggingface.co pre-approved as a bare hostname, so fetches to any path on that domain skipped the permission prompt, including paths in attacker-controlled model repositories. Requests to a repo's /resolve/... files increment Hugging Face's public download counters, and those counters became a covert channel: a prompt injection could encode data Claude had access to (file contents, environment variables) into patterns of fetches and read it back out from the public counts, with no prompt ever shown to the user. That's CVE-2026-54316, affecting versions 0.2.54 through 2.1.162 and fixed in 2.1.163; the full write-up is in the GitHub security advisory. Auto-updating installs had the fix before most people read the headline. Pinned and package-manager installs didn't, which is the entire argument for keeping the CLI current: an agent that fetches URLs and runs commands collects security fixes worth having within days, and the errors in this catalog are cheap by comparison. When something new breaks, the extension-side failures have their own diagnostic flow in my guide to fixing the Claude Code exited with code 1 error.
