Skip to content

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: EACCES permissions, npm 12 skipping postinstall, ENOTEMPTY leftover 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 claude says 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:

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:

StageWhat getting stuck looks likeTypical errorsCorresponding section on this page
1. DownloadThe install command never finishes, or downloads a web pagecurl: (22) The requested URL returned error: 403, syntax error near unexpected token '<'Download and network issues
2. InstallationWrong shell for the command, no directory permission, or npm install cut halfway'irm' is not recognized, EACCES, npm error code ENOTEMPTYWindows install command / npm installation issues
3. Command availabilityIt installed, but the shell can't find the commandzsh: command not found: claudeCommand availability (PATH) issues
4. LoginInstalled fine, but the login page spins or errors outOAuth error: Invalid codeLogin 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):

bash
# 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 doctor

Windows (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):

powershell
# 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 doctor

How to read the results:

Quick-test resultWhich checkpoint is stuckWhich section to go to
Command 1 prints a version numberInstallation fully passedLogin stuck → "Login authentication problems"
Command 1 reports command not found, command 2 shows files / TruePATH"Command availability (PATH) problems"
Command 2 says no such file, command 3 200Installation didn't finishGo back to Installing Claude Code and reinstall
Command 3 403 / no output / timeoutDownload and network"Download and network problems"
Version number prints, but startup crashes or hangsInstallation healthCommand 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:

  1. Wait a few minutes and retry the original command—this problem is often temporary.

  2. If that doesn't work, switch install channels (note: Homebrew / WinGet installs do not auto-update; you have to upgrade manually):

    macOS:

    bash
    brew install --cask claude-code

    Windows:

    powershell
    winget install Anthropic.ClaudeCode
  3. Open a new terminal to verify:

    bash
    claude --version

    You 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:

  1. First run the connectivity check from quick-test command 3:

    bash
    curl -sI https://downloads.claude.ai/claude-code-releases/latest
    • 403 → 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)
  2. 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:

    bash
    export HTTP_PROXY=http://proxy.example.com:8080
    export HTTPS_PROXY=http://proxy.example.com:8080
    curl -fsSL https://claude.ai/install.sh | bash

    Windows PowerShell:

    powershell
    $env:HTTP_PROXY = 'http://proxy.example.com:8080'
    $env:HTTPS_PROXY = 'http://proxy.example.com:8080'
    irm https://claude.ai/install.ps1 | iex
  3. Don'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:

  1. Update the system CA certificates. Ubuntu / Debian:

    bash
    sudo apt-get update && sudo apt-get install ca-certificates

    macOS system curl uses the Keychain trust store; updating macOS itself is enough.

  2. 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 | iex
  3. A corporate proxy doing TLS inspection triggers these errors—get the proxy's CA certificate from IT and add --cacert to the curl-based install command:

    bash
    curl --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:

  1. Check your region against the official supported list page.
  2. 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.
  3. 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:

powershell
irm https://claude.ai/install.ps1 | iex

Option 2: stay in CMD and use the CMD version of the install command:

batch
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

After 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:

powershell
irm https://claude.ai/install.ps1 | iex

Open 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):

  1. Check whether the file exists:

    bash
    ls -la ~/.local/bin/claude

    You should see: a file listing. No such file or directory = it was never installed; go back to Installing Claude Code and reinstall.

  2. Check whether this directory is in PATH:

    bash
    echo $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.

  3. Write it into your shell config and make it take effect immediately. macOS defaults to zsh:

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

    On Linux, bash uses ~/.bashrc by default; if you use bash on macOS, write to ~/.bash_profile (macOS Terminal starts bash as a login shell, which does not read ~/.bashrc).

  4. Verify:

    bash
    claude --version

    You 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 $0 to 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):

  1. Check whether the file exists:

    powershell
    Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

    You should see: True. False = it is not installed; go back to the installation lesson and reinstall.

  2. Add it to the User PATH (configure once):

    powershell
    $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
    [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
  3. Restart the terminal and run claude --version to 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):

powershell
Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

If 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):

  1. Allow local scripts (applies only to the current user), then retry:

    powershell
    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  2. Switch to the .cmd launchers instead: npm.cmd and claude.cmd do the same job, and the execution policy does not affect them.

  3. Switch to the official PowerShell installer—it installs a binary, not a .ps1:

    powershell
    irm 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:

  1. First run npm --version—if it starts with 12, it is an npm 12 issue; follow one of the two options below.

  2. Option 1 (recommended, fixes it once and for all): switch to the official native installer, then uninstall the npm version:

    bash
    curl -fsSL https://claude.ai/install.sh | bash
    npm uninstall -g @anthropic-ai/claude-code

    After the switch, updates no longer go through npm, so this error will not come back.

  3. Option 2: stay on npm—add Claude Code to allow-scripts and reinstall:

    bash
    npm config set "allow-scripts=@anthropic-ai/claude-code" --location=user
    npm install -g @anthropic-ai/claude-code

    Two notes: with npm 12.0.x, first run npm install -g npm@latest to upgrade to 12.1 or later; before setting, run npm config get allow-scripts to 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 reports EACCES, do not add sudo; switch to option 1 instead.

  4. The error message also provides a manual remedy (adjust the paths yourself for global/local installs):

    bash
    node 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:

  1. Check whether the directory is writable:

    bash
    test -w ~/.local/bin && echo "writable" || echo "not writable"
    test -w ~/.claude && echo "writable" || echo "not writable"
  2. If it is not writable, create the directory and take back ownership:

    bash
    sudo mkdir -p ~/.local/bin
    sudo chown -R $(whoami) ~/.local
  3. EACCES from an npm install → do not retry with sudo; switch to the official native installer:

    bash
    curl -fsSL https://claude.ai/install.sh | bash

    Reason: 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:

  1. Look at the directory named on the npm error path line in the error—that is the directory npm cannot move.

  2. Delete it along with any leftover .claude-code-* temporary directories nearby (macOS / Linux):

    bash
    rm -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:

    powershell
    Remove-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.

  3. Reinstall and verify:

    bash
    npm 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:

  1. In the session, enter /logout to fully log out
  2. Close Claude Code
  3. Run claude again 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:

  1. Press Enter to retry, and complete the login promptly once the browser opens.
  2. Browser didn't open automatically: enter c to copy the full URL and open your browser manually.
  3. 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:

  1. Claude Pro / Max / Ultra users: go to claude.ai/settings and confirm your subscription is active.
  2. Anthropic Console users: ask your administrator to add the "Claude Code" or "Developer" role to your account in platform.claude.com/settings/members.
  3. 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:

  1. 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).
  2. After the change, run claude to 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:

  1. Remove it for this session before starting (macOS / Linux):

    bash
    unset ANTHROPIC_API_KEY
    claude

    Windows PowerShell:

    powershell
    Remove-Item Env:ANTHROPIC_API_KEY
    claude
  2. Permanently: check for the export ANTHROPIC_API_KEY=... line in ~/.zshrc, ~/.bashrc, and ~/.profile and delete it; on Windows, check your PowerShell profile ($PROFILE) and user environment variables.

  3. Run /status in 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:

bash
# 证据三件套:版本、官方诊断报告、下载服务器连通性
claude --version                                            # 能出版本号,claude doctor 才跑得起来
claude doctor                                               # 官方自动诊断报告
curl -sI https://downloads.claude.ai/claude-code-releases/latest   # 网络连通性(Windows 用 curl.exe)

Where to ask:

ChannelWhen to go
GitHub IssuesInstallation problems: search known issues first; if none match, open a new issue with your OS, install command, and full error message
claude doctorVersion prints but behavior is wrong: first see what the diagnostic report says
/feedbackYou can get into a session: report the issue right in the session
Anthropic SupportAccount 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:

ErrorStage it blocksFirst step
zsh: command not found: claudeCommand worksls -la ~/.local/bin/claude Check the file, then configure PATH
syntax error near unexpected token '<'DownloadWait a few minutes and retry; if that fails, switch to Homebrew / WinGet
curl: (22) The requested URL returned error: 403Downloadcurl -sI https://downloads.claude.ai/claude-code-releases/latest Check connectivity
Error: claude native binary not installed.npmSwitch to the official native installer
OAuth error: Invalid code. Please make sure the full code was copiedLoginPress 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

Related Tutorials ​

gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.