Why does my terminal say claude: command not found?

The install directory is not on your PATH. The native installer puts claude in ~/.local/bin on macOS and Linux. Add that directory to PATH in ~/.zshrc or ~/.bashrc, then open a new terminal and run claude --version.

Why does Claude Code not work in the VS Code terminal?

The VS Code extension bundles a private copy of the CLI for its own panel and does not put claude on your PATH. Install Claude Code with the standalone installer, open a new terminal in VS Code, and run claude --version. For garbled text or Shift+Enter problems, run /terminal-setup.

What does claude doctor do?

It prints read-only diagnostics from the terminal without starting a session: install health, settings-file errors, the result of the last update and warnings with suggested fixes. Inside a session, /doctor runs a checkup that can also apply fixes after you confirm.

How do I fix a Claude Code login loop?

Run /logout, close Claude Code, start it again and sign in. In WSL2, over SSH or in a container, paste the code the browser shows at the prompt, or use claude auth login. If an old ANTHROPIC_API_KEY is set in your shell profile, remove it, since it overrides your subscription.

Claude Code Not Working? Fixes for the Common Errors

When Claude Code will not install, will not start or will not sign in, the error text nearly always names the cause. A fix list by symptom: command not found, failed installs, login loops, proxies and VPNs, terminal quirks, old versions, and where the logs are.

28 September 20268 min read

When Claude Code is not working, start with two commands: claude --version, which tells you whether your shell can find it at all, and claude doctor, which prints read-only diagnostics about the installation and your settings without starting a session. Most failures before or at startup then fall into one of six groups: the install directory is not on your PATH, the installer could not download, the sign-in did not complete, a proxy or VPN is in the way, the terminal is misbehaving, or the version is old. Each has a distinctive error, and each has a documented fix.

This list is for getting Claude Code to start. On Windows, the install commands and Windows-only errors are in Claude Code on Windows. If it starts but a session stalls, see Claude Code task stuck. If one MCP server will not connect, see Claude Code MCP server failed to connect.

The first two checks

Terminal

# Can the shell find it? Prints a version such as "2.1.211 (Claude Code)"
claude --version

# Read-only checkup: install health, settings errors, last update result
claude doctor

# Inside a running session, the checkup that can also apply fixes
/doctor

If claude --version fails, go to the next section. If it prints a version but claude crashes or hangs, claude doctor usually names the problem, and the sections after that cover the rest.

“command not found: claude”

The install finished, but your shell cannot find the program. The native installer puts it at ~/.local/bin/claude on macOS and Linux, and Anthropic’s installation troubleshooting page (opens in a new tab) says this error means that directory is not on your PATH. Check, then add it for your shell:

macOS and Linux

# Prints the directory if it is already on PATH
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

# Zsh (the macOS default)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# Bash on Linux (on macOS, Bash reads ~/.bash_profile instead)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

Open a new terminal before you test again. The window you installed from keeps its old PATH.
Not working in the VS Code terminal? The VS Code extension bundles its own private copy of the CLI for its chat panel and does not add claude to your PATH. If you only installed the extension, run the standalone installer to use claude from a terminal. More on the extension in Claude Code in VS Code.
Two versions fighting? which -a claude lists every claude on your PATH. Keep the native install and remove the others: npm uninstall -g @anthropic-ai/claude-code for an old npm install, rm -rf ~/.claude/local for the legacy local one, brew uninstall --cask claude-code for Homebrew.

The install itself fails

syntax error near unexpected token with <!DOCTYPE html>, or a bare curl: (22) ... 403: the install URL returned a web page instead of the script. The page may say the app is unavailable in your region; otherwise a proxy or firewall is usually blocking the download. Test with curl -sI https://downloads.claude.ai/claude-code-releases/latest, which should answer 200.
curl: (56) or curl: (23) Failure writing output to destination: the script arrived incomplete. If the connectivity check passes, retry; the failure is often intermittent.
Killed, or exit code 137, on a small Linux server: the out-of-memory killer stopped the install. It needs roughly 512 MB free, and running Claude Code needs at least 4 GB of RAM. Add swap or use a larger instance.
The install hangs in Docker: running the installer from / makes it scan the whole filesystem. Set WORKDIR /tmp before the install line.
TLS errors such as unable to get local issuer certificate: a proxy that inspects TLS is presenting its own certificate. Ask IT for the CA file, pass it to the install with curl --cacert, and set NODE_EXTRA_CA_CERTS to it for Claude Code itself.
Homebrew says No Cask with this name exists, or installs an old version: run brew update and try again. The claude-code cask tracks the stable channel, about a week behind; claude-code@latest tracks the newest release.

Sign-in loops and authentication errors

When sign-in fails and the reason is not obvious, reset it: run /logout, close Claude Code, start it again with claude and sign in afresh. If the browser does not open, press c at the login prompt to copy the URL and open it yourself. Then match the error:

OAuth error: Invalid code: the code expired or was cut short when you copied it. Retry and finish the browser step promptly.
The browser signs you in but nothing happens, in WSL2, over SSH or in a container: the browser is on another machine and cannot reach Claude Code’s local callback. It shows a code instead; paste it at Paste code here if prompted. If pasting does nothing, run claude auth login, which reads the code from standard input.
403 Forbidden after logging in: check the subscription is active; on a Console account, check you hold the Claude Code or Developer role; behind a proxy, fix the proxy first.
This organization has been disabled although your subscription is active: an old ANTHROPIC_API_KEY in your shell profile is overriding your sign-in. Unset it, remove it from the profile, and run /status to see which authentication method is in use.
Asked to log in again every session: /login fixes it for now. If it keeps happening, check the system clock, since token validation depends on it.
The free Claude.ai plan does not include Claude Code. You need Pro, Max, Team, Enterprise or a Console account, or a supported cloud provider.

Proxies, VPNs and firewalls

Errors such as Unable to connect to API, ECONNREFUSED, ENOTFOUND or Couldn't connect through your proxy mean a request never reached Anthropic. Run curl -I https://api.anthropic.com from the same shell. If that fails too, the network is the problem, not Claude Code.

Behind a corporate proxy

export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,.internal.example.com"
claude --debug   # the log confirms which proxy and certificates loaded

Claude Code reads the standard proxy variables once, at startup, and does not support SOCKS proxies, according to the network configuration guide (opens in a new tab). /status shows the proxy in use and marks one it could not parse.
The firewall must allow at least api.anthropic.com, claude.ai, platform.claude.com (sign-in and token refresh) and downloads.claude.ai (installs and updates). The guide lists the rest.
If curl works but Claude Code does not, look for a leftover ANTHROPIC_BASE_URL pointing at a gateway that is no longer running. It redirects every request away from Anthropic.
On macOS, a disconnected VPN can leave a stale tunnel interface behind; on Linux and WSL, check /etc/resolv.conf for an unreachable nameserver. Docker Desktop can intercept traffic too; quit it and retry.

Terminal problems on macOS, Linux and WSL

Shift+Enter sends instead of adding a line in VS Code, Cursor or Zed: run /terminal-setup once. In VS Code it also turns off GPU rendering in the integrated terminal, the usual cause of garbled characters there.
Option-key shortcuts do nothing on macOS: the terminal is not sending Option as Meta. In iTerm2 set the Option keys to “Esc+”; in Terminal.app tick “Use Option as Meta Key”. The terminal configuration page (opens in a new tab) covers other terminals and tmux.
dyld: cannot load or Symbol not found on a Mac: Claude Code requires macOS 13.0 or later. Other install methods download the same binary, so update macOS.
Illegal instruction on Linux: either the wrong architecture was downloaded, or the CPU lacks AVX, common on old processors and some virtual machines.
Error loading shared library libstdc++.so.6: you got the musl build on a glibc system, or you are on Alpine and need apk add libgcc libstdc++ ripgrep.
cannot execute binary file: Exec format error in WSL: you are on WSL 1. Convert with wsl --set-version <DistroName> 2. In WSL, keep the repository under /home/, not /mnt/c/, or search returns fewer results.

An old version

Many fixes in the documentation apply only from a given version, so update before you dig further. A native install updates itself in the background and switches over the next time you start it. claude update updates now, and claude doctor shows the result of the last attempt. Homebrew and WinGet installs do not update themselves: run brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode. The setup guide (opens in a new tab) also describes the stable release channel, about a week behind, if you would rather trail new releases. If claude update itself hangs after Checking for updates, rerun the install script instead.

Logs, a clean start, and reporting a bug

claude --debug writes a debug log to ~/.claude/debug/<session-id>.txt rather than the terminal. --debug-file <path> chooses the file, and --debug=mcp narrows it to one category.
claude --safe-mode starts with CLAUDE.md, plugins, hooks, skills and MCP servers switched off. If the problem goes away, one of your customisations is the cause.
/feedback inside a session sends the transcript and a description to Anthropic, and offers to open a prefilled GitHub issue. Without a session, search the Claude Code issues on GitHub (opens in a new tab) and include your operating system, the install command and the full error.
A spike of API Error: 5xx or 529 Overloaded may not be you at all; check status.claude.com (opens in a new tab) before changing anything.
Account problems, such as a subscription that is not recognised, go to Anthropic support from claude.ai, not to GitHub.

Write the fix down where the next person looks

Install problems repeat. The proxy variable, the CA file and the region block that cost you an hour will cost a colleague the same hour next month. Once Claude Code runs, connect it to your board with claude mcp add --transport http fenbs https://fenbs.ai/api/mcp and /mcp, and ask it to save the fix with fenbs_add_context_note. On fenbs that note becomes part of the board’s AI context, which every assistant connected to the board reads with fenbs_get_context before it starts. What else to keep there is in a task-tracking workflow for Claude Code.

Starting from scratch: Claude Code for beginners. The commands used above and the rest: Claude Code commands cheat sheet. Connecting the board: the Claude Code integration and the MCP docs.