What to do when it won't install: Getting-started troubleshooting with a 60-second quick check
You ran the commands from the installation lesson, typed claude and got nothing—don't rush to reinstall. Claude Code installation failures almost always get stuck at one of four stages: download, installation, command availability, login, and the errors at each stage look different. This page organizes the high-frequency errors from the official troubleshooting docs by "matching the exact text": first use the 60-second quick check to locate the stage, then follow the corresponding entry to fix it.
How to use this page: copy your error message verbatim, match it against the exact error text in the H4 headings below, and go straight to that entry's "cause + fix". If you can't find an exact match, run the 60-second quick check first to narrow it down. (Fact-checked 2026-11-04; commands and errors change with versions, so the official troubleshooting docs are authoritative.)
💡 Errors that appear only after a successful install are not covered on this page
This page covers "won't install, can't log in". If you can already chat normally and the error occurred during use (model errors, tools misbehaving), go to Error loop: feed the error message back as-is.
What you'll be able to do after this lesson
- Use 4 commands to pinpoint the stuck stage within 60 seconds: command availability, install files, network, installation health
- Fix
claude command not found/'claude' is not recognized(a one-time PATH setup—once done, you never touch it again) - Distinguish download-type errors (403, TLS, script turning into a web page) and know whether to retry, check the network, or switch install channels
- Handle the three big npm installation failures:
EACCESpermissions, npm 12 skipping postinstall,ENOTEMPTYleftover directories - When login gets stuck, troubleshoot with the "log out → restart → log back in" routine, and tell apart the symptoms of subscription, role, and API key override issues
Your current predicament
- The install command finished, but typing
claudesays command not found—did it actually install? - The error is a long string of English and you don't know whether to retry in place, check the network, or try a different install method all over again
- The install worked, but the login page spins or errors out and you can never get in
When to use this technique
When you need to:
- Fix errors stuck in Installing Claude Code or Alternative Installation Methods
- Spend 60 seconds pinpointing which stage the problem is in before posting for help
And you don't want to:
- Post on a forum and wait for replies at the first error—the quick check resolves most installation problems
- Keep reinstalling because you treat "download failed" as "not installed", making things messier
🎒 Preparation before you start
- You've run Installing Claude Code (getting stuck is fine—this page exists to unstick you)
- You know which terminal you have open: on macOS / Linux it's a terminal window; on Windows it's either PowerShell (prompt includes
PS) or CMD (without it) - You've copied the exact error text verbatim—matching it directly is much faster than describing it in translation
Core idea: The four stages of Claude Code installation failure
Locate the stage first, then look at the error. From running the install command to being able to chat, you pass four stages in order, and the errors at each stage look different:
| Stage | What getting stuck looks like | Typical errors | Corresponding section on this page |
|---|---|---|---|
| 1. Download | The install command never finishes, or downloads a web page | curl: (22) The requested URL returned error: 403, syntax error near unexpected token '<' | Download and network issues |
| 2. Installation | Wrong shell for the command, no directory permission, or npm install cut halfway | 'irm' is not recognized, EACCES, npm error code ENOTEMPTY | Windows install command / npm installation issues |
| 3. Command availability | It installed, but the shell can't find the command | zsh: command not found: claude | Command availability (PATH) issues |
| 4. Login | Installed fine, but the login page spins or errors out | OAuth error: Invalid code | Login authentication problems |
The exact error message is the key. The official troubleshooting docs index solutions by the exact error text, and this page follows the same approach: copy the error you hit verbatim and match it against the H4 headings below. Translated descriptions often won't match—if 'claude' is not recognized gets paraphrased as "unrecognized", you won't find the original fix.
The verification after any fix is the same one: open a new terminal and run claude --version; if it prints a version number (something like 2.1.211 (Claude Code)), you're good.
First-pass check: 60-second quick test
Run the four commands in order, verifying in turn that the command works, the files are installed, the network is fine, and the installation is healthy—whichever step breaks tells you which checkpoint the problem is at.
macOS / Linux (run in the terminal):
# 1. 命令可用吗?——能打印版本号 = 安装环节全过,卡的是登录,直接跳「登录认证问题」
claude --version
# 2. 安装文件在吗?——有列表输出 = 装上了,是 PATH 问题,跳「命令可用(PATH)问题」
# No such file or directory = 没装上,看第 3 条
ls -la ~/.local/bin/claude
# 3. 网络通吗?——第一行 HTTP/2 200 = 下载服务器可达,重装一次多半就好
# 403 或无输出 = 网络/地区问题,跳「下载与网络问题」
curl -sI https://downloads.claude.ai/claude-code-releases/latest
# 4. 安装健康吗?——第 1 条能出版本号、但 claude 一启动就崩或卡住时,跑官方自检看诊断报告
claude doctorWindows (run in PowerShell; note that curl must be written as curl.exe, because PowerShell's curl is an alias for Invoke-WebRequest and doesn't understand -sI):
# 1. 命令可用吗?——能打印版本号 = 安装环节全过,卡的是登录
claude --version
# 2. 安装文件在吗?——True = 装上了,是 PATH 问题;False = 没装上,看第 3 条
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
# 3. 网络通吗?——第一行 HTTP/1.1 200 OK = 下载服务器可达
curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest
# 4. 安装健康吗?——版本号能打印、但 claude 启动就崩或卡住时,跑官方自检
claude doctorHow to read the results:
| Quick-test result | Which checkpoint is stuck | Which section to go to |
|---|---|---|
| Command 1 prints a version number | Installation fully passed | Login stuck → "Login authentication problems" |
| Command 1 reports command not found, command 2 shows files / True | PATH | "Command availability (PATH) problems" |
| Command 2 says no such file, command 3 200 | Installation didn't finish | Go back to Installing Claude Code and reinstall |
| Command 3 403 / no output / timeout | Download and network | "Download and network problems" |
| Version number prints, but startup crashes or hangs | Installation health | Command 4 claude doctor; if it still fails → "Still not working?" |
Troubleshooting common problems
The H4 headings below are all exact error messages (or exact symptom text listed in the official docs)—match them verbatim. Each group corresponds to one checkpoint from the quick test.
Download and network problems
"syntax error near unexpected token '<'"
Cause: what the install command downloaded wasn't a script but a web page—bash executed the first line of the page, <!DOCTYPE html>, as a command. Usually caused by network issues, regional routing, or a temporary service outage. The corresponding symptom on Windows: CMD reports < was unexpected at this time., PowerShell throws a string of parse errors quoting HTML/CSS.
Fix:
Wait a few minutes and retry the original command—this problem is often temporary.
If that doesn't work, switch install channels (note: Homebrew / WinGet installs do not auto-update; you have to upgrade manually):
macOS:
bashbrew install --cask claude-codeWindows:
powershellwinget install Anthropic.ClaudeCodeOpen a new terminal to verify:
bashclaude --versionYou should see: a version number, something like
2.1.211 (Claude Code). If it still says command not found after installing, open a new terminal window and try again—the session you installed in still carries the old PATH.
Does the error quote App unavailable in region? Go straight to the region entry below.
"curl: (22) The requested URL returned error: 403"
Cause: the download host blocked the request. Two common sources: a proxy / network filter intercepting downloads.claude.ai, or your region not being on the official supported list.
Fix:
First run the connectivity check from quick-test command 3:
bashcurl -sI https://downloads.claude.ai/claude-code-releases/latest403→ proxy / network filtering, or a region issue (see the next entry)5xx→ temporary service outage; wait a few minutes and retry- No output /
Could not resolve host/ connection timeout → the network is blocking the connection: a corporate firewall, regional network restrictions, or a TLS issue (see the TLS entry)
Still getting 403 in a supported region → check your proxy. On a corporate network, ask IT for the proxy address, set it up before installing, then run the install command:
bashexport HTTP_PROXY=http://proxy.example.com:8080 export HTTPS_PROXY=http://proxy.example.com:8080 curl -fsSL https://claude.ai/install.sh | bashWindows PowerShell:
powershell$env:HTTP_PROXY = 'http://proxy.example.com:8080' $env:HTTPS_PROXY = 'http://proxy.example.com:8080' irm https://claude.ai/install.ps1 | iexDon't rush to switch channels: the alternative installer connects to the same hosts, so if the network is down, switching channels won't help—fix the network first.
"curl: (35) TLS connect error"
Cause: TLS handshake failure—outdated system CA certificates, a corporate proxy doing TLS inspection, or Windows PowerShell 5.1 not enabling TLS 1.2 by default. Same-family errors: Could not create SSL/TLS secure channel, unable to get local issuer certificate, SELF_SIGNED_CERT_IN_CHAIN.
Fix:
Update the system CA certificates. Ubuntu / Debian:
bashsudo apt-get update && sudo apt-get install ca-certificatesmacOS system curl uses the Keychain trust store; updating macOS itself is enough.
On Windows PowerShell 5.1, enable TLS 1.2 first, then run the installer in the same window:
powershell[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 irm https://claude.ai/install.ps1 | iexA corporate proxy doing TLS inspection triggers these errors—get the proxy's CA certificate from IT and add
--cacertto the curl-based install command:bashcurl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
"App unavailable in region"
Cause: your region isn't on Anthropic's official supported list—the list excludes mainland China, Hong Kong, and Macau. This is an official policy restriction, not an installation failure.
Fix:
- Check your region against the official supported list page.
- Switching install channels won't get around it—npm, Homebrew, and WinGet all connect to the same service, and the regional restriction doesn't change based on how you install.
- If you want to start vibe coding right now, switch to tools that don't need an overseas account: WorkBuddy (from Tencent, log in by scanning a QR code in WeChat, zero command line) or OpenCode, which can connect to domestic models. For choosing between them, see How to choose among the four tools; for WorkBuddy installation, see Alternative installation methods.
Windows install command problems
"'irm' is not recognized as an internal or external command"
Cause: irm is a PowerShell command—you ran the PowerShell install command in CMD, so the command and the shell don't match.
Fix (pick one of the two):
Option 1: open PowerShell—search "PowerShell" in the Start menu and run the original command:
irm https://claude.ai/install.ps1 | iexOption 2: stay in CMD and use the CMD version of the install command:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmdAfter installing, open a new terminal and run claude --version to verify.
By the way: The token '&&' is not a valid statement separator is the reverse mistake—running a CMD command in PowerShell; likewise, switch to the irm version.
"A parameter cannot be found that matches parameter name 'fsSL'"
Cause: you ran the macOS / Linux curl -fsSL ... | bash in Windows PowerShell—there curl is an alias for Invoke-WebRequest and doesn't understand arguments like -fsSL.
Fix: on Windows, use the PowerShell version of the install command:
irm https://claude.ai/install.ps1 | iexOpen a new terminal and run claude --version to verify.
Command availability (PATH) issues
"zsh: command not found: claude"
Cause: It is installed, but the install directory ~/.local/bin is not in PATH, so the shell cannot find claude. The installer actually warned you: Native installation exists but ~/.local/bin is not in your PATH.. The equivalent error on Linux is bash: claude: command not found.
Solution (macOS / Linux, configure PATH once and it takes effect permanently):
Check whether the file exists:
bashls -la ~/.local/bin/claudeYou should see: a file listing.
No such file or directory= it was never installed; go back to Installing Claude Code and reinstall.Check whether this directory is in PATH:
bashecho $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"Output = it is in PATH, the problem lies elsewhere; see the troubleshooting points in step 4. No output = it is not; add it in the next step.
Write it into your shell config and make it take effect immediately. macOS defaults to zsh:
bashecho 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrcOn Linux, bash uses
~/.bashrcby default; if you use bash on macOS, write to~/.bash_profile(macOS Terminal starts bash as a login shell, which does not read~/.bashrc).Verify:
bashclaude --versionYou should see: a version number. Still not found? Three common causes:
- An old terminal window carries the old PATH—open a new window;
- An editor's built-in terminal inherits the editor's PATH—quit and restart the editor;
- The config was written into another shell's file—run
echo $0to see which shell you are currently using, and configure that shell.
"'claude' is not recognized as an internal or external command"
Cause: The same PATH issue on Windows—%USERPROFILE%\.local\bin is not in PATH. In PowerShell the error looks like claude : The term 'claude' is not recognized as the name of a cmdlet.
Solution (PowerShell):
Check whether the file exists:
powershellTest-Path "$env:USERPROFILE\.local\bin\claude.exe"You should see:
True.False= it is not installed; go back to the installation lesson and reinstall.Add it to the User PATH (configure once):
powershell$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User') [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')Restart the terminal and run
claude --versionto verify. If it still fails, check whether the output of[Environment]::GetEnvironmentVariable('PATH', 'User')contains.local\bin; if not, rerun step 2. For an editor's built-in terminal, restart the editor.
CMD users: use dir "%USERPROFILE%\.local\bin\claude.exe" to confirm the file and echo %PATH% | findstr /i "local\bin" to check PATH; if it is missing, go to System Settings → Environment Variables, add %USERPROFILE%\.local\bin to the user PATH, and restart the terminal.
Special case: on Windows, if this error appears right after an update → the update process may have moved claude.exe into a backup. The recovery command given in the official docs (rename the latest backup back to the original name):
Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exeIf there is no claude.exe.old.* backup, or it still fails after the rename → reinstall: irm https://claude.ai/install.ps1 | iex.
npm installation issues
"running scripts is disabled on this system"
Cause: You installed Claude Code on Windows with npm, and PowerShell's execution policy blocked the .ps1 launcher script generated by npm (the error also mentions PSSecurityException). When you run claude, the error names claude.ps1. The official PowerShell installer is unaffected—it executes the downloaded text directly, without going through a script file.
Solution (pick one of three):
Allow local scripts (applies only to the current user), then retry:
powershellSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserSwitch to the
.cmdlaunchers instead:npm.cmdandclaude.cmddo the same job, and the execution policy does not affect them.Switch to the official PowerShell installer—it installs a binary, not a
.ps1:powershellirm https://claude.ai/install.ps1 | iex
"Error: claude native binary not installed."
Cause: The claude in the npm package is just a placeholder script; the postinstall step is responsible for replacing it with the real binary (binaries are published as optional dependencies per platform, e.g. @anthropic-ai/claude-code-darwin-arm64). If the download or postinstall was skipped, the placeholder script is left behind. Most common triggers: npm 12 skips postinstall by default, --omit=optional disables optional dependencies, and --ignore-scripts disables install scripts.
Fix:
First run
npm --version—if it starts with 12, it is an npm 12 issue; follow one of the two options below.Option 1 (recommended, fixes it once and for all): switch to the official native installer, then uninstall the npm version:
bashcurl -fsSL https://claude.ai/install.sh | bash npm uninstall -g @anthropic-ai/claude-codeAfter the switch, updates no longer go through npm, so this error will not come back.
Option 2: stay on npm—add Claude Code to
allow-scriptsand reinstall:bashnpm config set "allow-scripts=@anthropic-ai/claude-code" --location=user npm install -g @anthropic-ai/claude-codeTwo notes: with npm 12.0.x, first run
npm install -g npm@latestto upgrade to 12.1 or later; before setting, runnpm config get allow-scriptsto check the existing list—the setting command replaces the entire list, so if it contains other packages, include them inside the quotes as well. If this step reportsEACCES, do not add sudo; switch to option 1 instead.The error message also provides a manual remedy (adjust the paths yourself for global/local installs):
bashnode node_modules/@anthropic-ai/claude-code/install.cjs
"EACCES: permission denied"
Cause: The directories the installation needs to write to are not writable. The native installer writes to ~/.claude/downloads/, ~/.local/bin/, ~/.local/share/claude/ and similar locations on macOS / Linux; an EACCES error from an npm install is a permissions issue with npm's global directory.
Fix:
Check whether the directory is writable:
bashtest -w ~/.local/bin && echo "writable" || echo "not writable" test -w ~/.claude && echo "writable" || echo "not writable"If it is not writable, create the directory and take back ownership:
bashsudo mkdir -p ~/.local/bin sudo chown -R $(whoami) ~/.localEACCES from an npm install → do not retry with sudo; switch to the official native installer:
bashcurl -fsSL https://claude.ai/install.sh | bashReason: Claude Code runs npm without sudo when updating itself; packages installed with sudo will fail in the same way during automatic updates.
"npm error code ENOTEMPTY"
Cause: You reinstalled or updated over an existing installation, and when npm tried to move the old package directory it found the directory non-empty and the rename failed—usually leftover directories from a previously interrupted install.
Fix:
Look at the directory named on the
npm error pathline in the error—that is the directory npm cannot move.Delete it along with any leftover
.claude-code-*temporary directories nearby (macOS / Linux):bashrm -rf "$(npm root -g)/@anthropic-ai/claude-code" rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*Zsh reporting
no matches found= there are no leftovers to delete; that is normal. On Windows PowerShell:powershellRemove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"Note: when the directory named in the error is not under
npm root -g(for example, if you switched Node versions with nvm), delete it following the path given in the error instead of guessing with the commands above.Reinstall and verify:
bashnpm install -g @anthropic-ai/claude-code claude --version
Login and authentication issues
When login is stuck and the cause is unclear, first run the officially recommended "three-step combo", which resolves most cases:
- In the session, enter
/logoutto fully log out - Close Claude Code
- Run
claudeagain and go through the full authentication flow
Browser didn't open automatically? Press c to copy the login URL and paste it into your browser manually. This also works when a link wraps in a narrow SSH terminal and can't be clicked.
"OAuth error: Invalid code. Please make sure the full code was copied"
Cause: The login code expired, or it got truncated when copied.
Fix:
- Press Enter to retry, and complete the login promptly once the browser opens.
- Browser didn't open automatically: enter
cto copy the full URL and open your browser manually. - SSH / remote sessions: the browser may have opened on the remote machine—copy the URL shown in the terminal and open it in your local browser.
"API Error: 403 Request not allowed"
Cause: Login succeeded, but the request was denied. Three possibilities with identical symptoms—match yours: an inactive subscription, a Console account without the right role, or a proxy interfering with API requests.
Fix:
- Claude Pro / Max / Ultra users: go to claude.ai/settings and confirm your subscription is active.
- Anthropic Console users: ask your administrator to add the "Claude Code" or "Developer" role to your account in platform.claude.com/settings/members.
- A corporate proxy can interfere with API requests: check the proxy settings in your network configuration.
"Claude Code access has not been granted for this account"
Cause: Your Claude enterprise organization set your role to Custom, and none of the custom roles assigned to you include Claude Code permissions. Changing things inside Claude Code won't help—an administrator has to act.
Fix:
- Contact your organization Owner: assign a custom role with Claude Code to your group, or change your role from Custom to a standard role like User (roles are managed in the organization's role settings).
- After the change, run
claudeto log in again.
"This organization has been disabled"
Cause: Your subscription is clearly active, yet it reports the organization is disabled—most likely a leftover ANTHROPIC_API_KEY environment variable in your shell is overriding the subscription login. The most common case: a key from a previous company or an old project still sitting in your configuration.
Fix:
Remove it for this session before starting (macOS / Linux):
bashunset ANTHROPIC_API_KEY claudeWindows PowerShell:
powershellRemove-Item Env:ANTHROPIC_API_KEY claudePermanently: check for the
export ANTHROPIC_API_KEY=...line in~/.zshrc,~/.bashrc, and~/.profileand delete it; on Windows, check your PowerShell profile ($PROFILE) and user environment variables.Run
/statusin the session to confirm the currently active authentication method is your subscription, not an API key.
Still not working?
Gather evidence before asking a question. Your operating system + the install command you ran + the full original error message beat a hundred sentences of description. If claude --version still prints a version number, include the official self-check report too:
# 证据三件套:版本、官方诊断报告、下载服务器连通性
claude --version # 能出版本号,claude doctor 才跑得起来
claude doctor # 官方自动诊断报告
curl -sI https://downloads.claude.ai/claude-code-releases/latest # 网络连通性(Windows 用 curl.exe)Where to ask:
| Channel | When to go |
|---|---|
| GitHub Issues | Installation problems: search known issues first; if none match, open a new issue with your OS, install command, and full error message |
claude doctor | Version prints but behavior is wrong: first see what the diagnostic report says |
/feedback | You can get into a session: report the issue right in the session |
| Anthropic Support | Account issues: login loops, subscription not recognized, organization disabled—log in to claude.ai, click your avatar in the bottom-left corner, and choose Get help |
Checkpoints ✅
- Ran the 4 quick-check commands and know which stage you're stuck at
command not found: I first check whether the file exists, then check PATH—configure once and it works permanently- My error message matches one of the H4 entries; I fixed it step by step and verified with
claude --version - For login hangs, I first run the three-step combo "log out → restart → log back in," then match symptoms across subscription / role / API key
- Before asking a question, I have the three essentials ready: operating system + install command + full original error message
Lesson Summary
✅ For Claude Code installation failures, first pinpoint the stage, then read the error: download (network/region) → install (command/permissions/npm) → command works (PATH) → login (authentication/subscription/role).
✅ Every high-frequency error has a fix: command not found is a one-time PATH setup; 403 and scripts turning into web pages—check the network first, then switch channels; for the three big npm failures (EACCES, npm 12 skipping postinstall, ENOTEMPTY), switching to the official native installer is the easiest route.
✅ Login problems sorted by symptom: subscriptions—check settings; roles—ask your administrator; API key override—clear the environment variable; run the three-step combo (log out → restart → log back in) first.
✅ Verification after any fix comes down to one thing: open a new terminal and claude --version prints the version number.
Quick reference for key errors:
| Error | Stage it blocks | First step |
|---|---|---|
zsh: command not found: claude | Command works | ls -la ~/.local/bin/claude Check the file, then configure PATH |
syntax error near unexpected token '<' | Download | Wait a few minutes and retry; if that fails, switch to Homebrew / WinGet |
curl: (22) The requested URL returned error: 403 | Download | curl -sI https://downloads.claude.ai/claude-code-releases/latest Check connectivity |
Error: claude native binary not installed. | npm | Switch to the official native installer |
OAuth error: Invalid code. Please make sure the full code was copied | Login | Press Enter to retry; c copy the URL and open the browser manually |
Next Lesson Preview
Installed and logged in—startup troubleshooting ends here, and your tools are in place. Next up: Daily use: the correct way to use each of the four tools.
You will learn:
- Claude Code: the correct way to use it in the terminal—how to start, how to converse
- Codex, OpenCode, and WorkBuddy: the right way to get started with each
- Price comparison of the four tools: know exactly how much you're spending