Troubleshoot installation and login changedtroubleshoot-install
Nearest release: v2.1.296, published 4 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 9 Oct 2026 20:59 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 9 Oct 2026 21:07 UTC.
Upstream edited
Recorded here
Lines+169added
Lines−13removed
From line
11
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits22to this page, all time
### `permission denied` when adding to your PATH ### The connection dropped while downloading the update ### Installation was killed before it could finish
The whole hunk
from line 11, old and new numbered
/
from line 11
1111| What you see | Solution |
1212| :- | :- |
1313| `command not found: claude` or `'claude' is not recognized` | [Fix your PATH](#command-not-found-claude-after-installation) |
14| `Native installation exists but ... is not in your PATH` | [Add the install directory to your PATH](#verify-your-path) |
15| `INFO: Could not find files for the given pattern(s).` from `where.exe claude` | [Check whether Claude Code is installed](#check-for-conflicting-installations) |
16| `zsh: permission denied: /Users/you/.zshrc` or `bash: /home/you/.bashrc: Permission denied` | [Make your shell config file writable](#permission-denied-when-adding-to-your-path) |
1417| `syntax error near unexpected token '<'` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |
18| `< was unexpected at this time` in CMD | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |
19| `The term 'System.Xml.XmlDocument' is not recognized` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |
1520| `curl: (22) The requested URL returned error: 403` | [Install script returned 403](#install-script-returns-html-instead-of-a-shell-script) |
1621| `curl: (23)` or `curl: (56) Failure writing output to destination` | [Check connectivity or use an alternative installer](#curl-56-failure-writing-output-to-destination) |
17| `Killed` during install on Linux, or `Installation was killed before it could finish (exit code 137)` | [Free memory or add swap space](#install-killed-on-low-memory-linux-servers) |
22| `Killed` during install on Linux | [Free memory or add swap space](#install-killed-on-low-memory-linux-servers) |
23| `Installation was killed before it could finish` | [Free memory, then rerun the installer](#installation-was-killed-before-it-could-finish) |
1824| `Raw mode is not supported` during install | [Rerun the installer](#raw-mode-is-not-supported-during-install) |
1925| `EACCES: permission denied` during install | [Fix the install directory's permissions](#permission-errors-during-installation) |
2026| `TLS connect error` or `SSL/TLS secure channel` | [Update CA certificates](#tls-or-ssl-connection-errors) |
27| `CRYPT_E_NO_REVOCATION_CHECK` or `CRYPT_E_REVOCATION_OFFLINE` | [Work around blocked revocation checks](#tls-or-ssl-connection-errors) |
2128| `Failed to fetch version` or can't reach download server | [Check network and proxy settings](#check-network-connectivity) |
29| `The connection dropped while downloading the update` or `Download timed out: exceeded the total deadline` | [Run the update again or set your proxy](#the-connection-dropped-while-downloading-the-update) |
2230| `irm is not recognized` or `The token '&&' is not a valid statement separator` | [Use the right command for your shell](#wrong-install-command-on-windows) |
2331| `Cask 'claude-code' is unavailable: No Cask with this name exists` | [Update Homebrew](#homebrew-cask-unavailable-or-outdated) |
32| `Cask 'claude-code@latest' is not installed` | [Upgrade the cask you installed](#cask-is-not-installed) |
2433| `'bash' is not recognized as the name of a cmdlet` | [Use the Windows installer command](#wrong-install-command-on-windows) |
2534| `A parameter cannot be found that matches parameter name 'fsSL'` | [Use the Windows installer command](#wrong-install-command-on-windows) |
2635| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [Install a shell](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |
from line 122
113122
114123If installation succeeded but you get a `command not found` or `not recognized` error when running `claude`, the install directory isn't in your PATH. Your shell searches for programs in directories listed in PATH, and the installer places `claude` at `~/.local/bin/claude` on macOS/Linux or `%USERPROFILE%\.local\bin\claude.exe` on Windows.
115124
125The installer detects this case and reports it under `Setup notes:` in its output: `Native installation exists but ~/.local/bin is not in your PATH.` on macOS and Linux, or `Native installation exists but C:\Users\you\.local\bin is not in your PATH.` on Windows. It prints the fix with that note but doesn't change PATH itself.
126
116127<Note>
117128 The [VS Code extension](/docs/en/vs-code) does not place `claude` at this location. It bundles a private copy of the CLI inside the extension directory for its own chat panel and does not add it to PATH. If you have only installed the extension, `~/.local/bin/claude` will not exist. Run the [standalone install](/docs/en/setup) to use `claude` from a terminal, then continue below.
118129</Note>
119130
120Check if the install directory is in your PATH by listing your PATH entries and filtering for `local/bin`:
131First check that the program is there at all, then check whether its folder is in your PATH. The PATH fix is permanent, so you apply it once. Pick your platform's tab and run its commands there: in your terminal on macOS and Linux, or in PowerShell or Command Prompt on Windows.
121132
122133<Tabs>
123134 <Tab title="macOS/Linux">
135 Check that the installer put the program in place:
136
124137 ```bash theme={null}
138 ls -la ~/.local/bin/claude
139 ```
140
141 * **`No such file or directory`**: there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, [install Claude Code](/docs/en/setup#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
142 * **A listing for the file**: the program is there. Check your PATH next.
143
144 List your PATH entries and filter for the install folder:
145
146 ```bash theme={null}
125147 echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
126148 ```
127149
128 If this prints `/Users/you/.local/bin` or `/home/you/.local/bin`, the directory is in your PATH and you can skip to [Check for conflicting installations](#check-for-conflicting-installations). If there's no output, add it to your shell configuration.
150 If this prints `/Users/you/.local/bin` or `/home/you/.local/bin`, the directory is in your PATH and you can skip to [Check for conflicting installations](#check-for-conflicting-installations). If there's no output, add it to your shell configuration with the two commands for your shell. The `echo` command saves the setting for every new terminal, and `source` applies it to the window you're in. The `echo` command prints nothing when it succeeds.
129151
130152 For Zsh, the default on macOS:
131153
from line 172
150172
151173 Alternatively, close and reopen your terminal.
152174
175 If the `echo` command prints `permission denied`, see [`permission denied` when adding to your PATH](#permission-denied-when-adding-to-your-path).
176
153177 For other shells such as fish or Nushell, add `~/.local/bin` to your PATH using your shell's own configuration syntax, then restart your terminal.
154178
155179 Verify the fix worked:
from line 181
157181 ```bash theme={null}
158182 claude --version
159183 ```
184
185 If `claude` is still not found, check these causes:
186
187 * **The terminal predates the change**: a window that was already open keeps its old PATH, and a terminal inside an editor takes its PATH from the editor. Open a new window, or quit and reopen the editor.
188 * **The line wasn't saved**: run `grep -n '.local/bin' ~/.zshrc`, using your shell's file name. It prints the line with its line number when the line is there. If it prints nothing, run the two PATH commands again.
189 * **The line went to another shell's file**: run `echo $0` to see your shell, then run the two PATH commands for that shell.
160190 </Tab>
161191
162192 <Tab title="Windows PowerShell">
193 Check that the installer put the program in place:
194
163195 ```powershell theme={null}
196 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
197 ```
198
199 * **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](/docs/en/setup#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
200 * **`True`**: the program is there. Check your PATH next.
201
202 List your PATH entries and filter for the install folder:
203
204 ```powershell theme={null}
164205 $env:PATH -split ';' | Select-String '\.local\\bin'
165206 ```
166207
167 If there's no output, add the install directory to your User PATH:
208 If this prints `C:\Users\you\.local\bin`, the directory is in your PATH and you can skip to [Check for conflicting installations](#check-for-conflicting-installations). If there's no output, add the install directory to your User PATH:
168209
169210 ```powershell theme={null}
170211 $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
from line 219
178219 ```powershell theme={null}
179220 claude --version
180221 ```
222
223 If `claude` is still not found in a new terminal, check these causes:
224
225 * **The terminal runs inside an editor**: it takes its PATH from the editor, so quit and reopen the editor.
226 * **The change wasn't saved**: run `[Environment]::GetEnvironmentVariable('PATH', 'User')` and look for `.local\bin` in the PATH it prints. If it's missing, run the two commands again.
181227 </Tab>
182228
183229 <Tab title="Windows CMD">
230 Check that the installer put the program in place:
231
184232 ```batch theme={null}
233 dir "%USERPROFILE%\.local\bin\claude.exe"
234 ```
235
236 * **`File Not Found` or `The system cannot find the path specified.`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](/docs/en/setup#install-claude-code). If you installed it another way, see [Check for conflicting installations](#check-for-conflicting-installations).
237 * **A listing for `claude.exe`**: the program is there. Check your PATH next.
238
239 List your PATH entries and filter for the install folder:
240
241 ```batch theme={null}
185242 echo %PATH% | findstr /i "local\bin"
186243 ```
187244
from line 249
192249 ```batch theme={null}
193250 claude --version
194251 ```
252
253 If `claude` is still not found in a new terminal, a terminal inside an editor takes its PATH from the editor, so quit and reopen the editor too.
195254 </Tab>
196255</Tabs>
197256
from line 266
207266 which -a claude
208267 ```
209268
210 If this prints nothing, no `claude` is on your PATH yet. Go back to [Verify your PATH](#verify-your-path).
269 If this prints `claude not found`, a `no claude in` line, or nothing, no `claude` is on your PATH. The next checks show whether one is installed at all.
211270
212271 Check the three locations a `claude` binary can come from. `~/.local/bin/claude` is the native installer, `~/.claude/local/` is a legacy local npm install created by older versions of Claude Code, and the npm global list shows a `-g` install:
213272
from line 285
226285 ```bash theme={null}
227286 npm -g ls @anthropic-ai/claude-code 2>/dev/null
228287 ```
288
289 If `ls -la ~/.local/bin/claude` printed `No such file or directory`, there's no native install. If you haven't installed Claude Code another way, such as with npm, Homebrew, or a Linux package manager, [install Claude Code](/docs/en/setup#install-claude-code). If `~/.local/bin/claude` exists but `which -a claude` didn't list it, the folder isn't in your PATH: see [Verify your PATH](#verify-your-path).
229290 </Tab>
230291
231292 <Tab title="Windows PowerShell">
from line 296
235296 where.exe claude
236297 ```
237298
299 If this prints `INFO: Could not find files for the given pattern(s).`, no `claude` is on your PATH.
300
238301 Check whether the native installer placed a binary:
239302
240303 ```powershell theme={null}
241304 Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
242305 ```
306
307 * **`True`**: the native install is there. If `where.exe` found nothing, its folder isn't in your PATH: see [Verify your PATH](#verify-your-path).
308 * **`False`**: there's no native install. If you haven't installed Claude Code another way, such as with npm or WinGet, [install Claude Code](/docs/en/setup#install-claude-code).
243309 </Tab>
244310</Tabs>
245311
from line 412
346412
347413### Install script returns HTML instead of a shell script
348414
349When running the install command, you may see one of these errors:
415The install command fails with one of these errors when what it downloaded isn't the install script.
350416
417**Bash or Zsh**: the error quotes the first line of the returned page.
418
351419```text theme={null}
352420bash: line 1: syntax error near unexpected token `<'
353421bash: line 1: `<!DOCTYPE html>'
354422```
355423
356On PowerShell, the same problem appears as parse errors pointing into the returned page, with `iex` trying to run HTML and CSS as PowerShell:
424**PowerShell, parse errors**: the errors point into the returned page, with `iex` trying to run HTML and CSS as PowerShell.
357425
358426```text theme={null}
359427iex : At line:1 char:2310
from line 432
364432
365433The wording varies with the PowerShell version and system language: you may see `Missing expression after unary operator '--'` or a `ParserError` with `ParseException` instead. HTML tags or CSS in the quoted text identify this failure. If you download with `-OutFile install.ps1` instead, the saved file is the same web page, so that doesn't help either.
366434
367Depending on how the request was routed, you may instead see a 403 with no HTML body:
435**PowerShell, `System.Xml.XmlDocument`**: the error names this type instead of quoting the page.
368436
369437```text theme={null}
438System.Xml.XmlDocument : The term 'System.Xml.XmlDocument' is not recognized as the name of a cmdlet, function, script
439file, or operable program.
440```
441
442When `irm` can parse the response as XML, it returns an XML object instead of text, and `iex` then tries to run that object's type name as a command. The install script is PowerShell code and doesn't parse as XML, so this error also means the response was something other than the script. The wording around the type name varies with the PowerShell version and system language, but `System.Xml.XmlDocument` itself stays the same, so match on the type name.
443
444**CMD**: you see this error, followed by the HTML of the returned page.
445
446```text theme={null}
447< was unexpected at this time.
448
449C:\Users\you><!DOCTYPE html>...
450```
451
452The first line appears in your system language, so look for the HTML that follows it.
453
454**A 403 with no page**: depending on how the request was routed, curl reports a 403 status with no HTML body.
455
456```text theme={null}
370457curl: (22) The requested URL returned error: 403
371458```
372459
373These all mean the install URL returned an HTML page or an error status instead of the install script. If the HTML page says "App unavailable in region," Claude Code is not available in your country. See [supported countries](https://www.anthropic.com/supported-countries).
460These all mean the install URL returned a web page, an XML document, or an error status instead of the install script. If the error output quotes "App unavailable in region," Claude Code isn't available in your country. See [supported countries](https://www.anthropic.com/supported-countries).
374461
375462A bare 403 with no body often has the same cause, but it can also come from a corporate proxy or firewall blocking the download. If you are in a supported country and still see the 403, work through [Check network connectivity](#check-network-connectivity) before trying the alternative installers below, since those reach the same hosts.
376463
from line 465
378465
379466**Solutions:**
380467
3811. **Use an alternative install method**:
4681. **Retry after a few minutes**: the issue is often temporary. Wait and try the original command again.
382469
4702. **Use an alternative install method**: unlike a native install, a Homebrew or WinGet install [doesn't update itself by default](/docs/en/setup#auto-updates).
471
383472 On macOS, install via Homebrew:
384473
385474 ```bash theme={null}
from line 483
394483
395484 Then run `claude --version` to confirm: the command prints a version number such as `2.1.211 (Claude Code)`. If the shell reports `claude` isn't found, open a new terminal window and retry: the session you installed from keeps its old `PATH`.
396485
3972. **Retry after a few minutes**: the issue is often temporary. Wait and try the original command again.
398
399486### `command not found: claude` after installation
400487
401488The install finished but `claude` doesn't work. The exact error varies by platform:
from line 498
411498
412499Otherwise, see [Verify your PATH](#verify-your-path) for the fix on each platform.
413500
501### `permission denied` when adding to your PATH
502
503If the `echo` command that adds `~/.local/bin` to your PATH prints `zsh: permission denied: /Users/you/.zshrc` or `bash: /home/you/.bashrc: Permission denied`, your user can't write to that file and nothing was saved. In your terminal, check who owns the file, using your shell's file name in place of `~/.zshrc`:
504
505```bash theme={null}
506ls -l ~/.zshrc
507```
508
509The third field of the output is the owner.
510
511* **The owner is another user, such as `root`**: take ownership with `sudo chown $(whoami) ~/.zshrc`, which requires administrator rights.
512* **The owner is you**: the file is read-only. Make it writable with `chmod u+w ~/.zshrc`.
513
514Then run the two PATH commands for your shell in [Verify your PATH](#verify-your-path) again.
515
414516### `curl: (56) Failure writing output to destination`
415517
416518The `curl ... | bash` command downloads the script and pipes it to Bash for execution. This error, and the related `curl: (23) Failure writing output to destination`, means Bash did not receive the complete script. Exit code 56 indicates the download itself was interrupted, and exit code 23 indicates curl could not write what it received to the pipe, usually because Bash exited early.
from line 530
428530
429531If Homebrew installs an older Claude Code version than you expect, the same stale index is usually the cause. The `claude-code` cask tracks the stable channel and is typically about one week behind the latest release; for the newest version run `brew install --cask claude-code@latest` instead. See [Configure release channel](/docs/en/setup#configure-release-channel) for the difference between the two casks.
430532
533<h3 id="cask-is-not-installed">
534 `Cask 'claude-code@latest' is not installed`
535</h3>
536
537Homebrew offers two casks, `claude-code` and `claude-code@latest`. Running `brew upgrade --cask claude-code@latest` when that cask isn't the one installed prints `Error: Cask 'claude-code@latest' is not installed.` To see which cask you have, run this in your terminal:
538
539```bash theme={null}
540brew list --cask | grep claude-code
541```
542
543Upgrade the cask it prints. If it prints nothing, neither cask is installed.
544
431545### TLS or SSL connection errors
432546
433547Errors such as these mean the TLS handshake failed:
from line 551
437551* PowerShell's `Could not create SSL/TLS secure channel`
438552* PowerShell's `Could not establish trust relationship for the SSL/TLS secure channel`
439553
554For `CRYPT_E_NO_REVOCATION_CHECK` or `CRYPT_E_REVOCATION_OFFLINE`, go to step 4.
555
440556**Solutions:**
441557
4425581. **Update your system CA certificates**:
from line 565
449565
450566 On macOS, the system curl uses the Keychain trust store; updating macOS itself updates the root certificates.
451567
4522. **On Windows, enable TLS 1.2** in PowerShell before running the installer:
5682. **In Windows PowerShell 5.1, enable TLS 1.2**:
453569 ```powershell theme={null}
454570 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
571 ```
572 Then run the installer in the same window:
573 ```powershell theme={null}
455574 irm https://claude.ai/install.ps1 | iex
456575 ```
457576
from line 624
505624
506625The installer couldn't reach the download server. This typically means `downloads.claude.ai` is blocked on your network. See [Check network connectivity](#check-network-connectivity).
507626
627### The connection dropped while downloading the update
628
629The connection to the download server closed while `claude install` or `claude update` was fetching the Claude Code binary, and the retries didn't recover. Claude Code retries the download when the connection drops, the transfer stalls, or the downloaded file fails its checksum, up to three attempts in total. A completed HTTP error, such as a 404, isn't retried because the server already answered. Before v2.1.202, a single dropped connection failed the download immediately with the bare error `aborted` instead of retrying.
630
631```text theme={null}
632The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.
633```
634
635The text in parentheses names which attempt failed and the underlying network error. `claude update` precedes the message with `Error: Failed to install native update` on stderr.
636
637A download that stays connected but doesn't finish within 10 minutes fails with `Download timed out: exceeded the total deadline` instead. Claude Code doesn't retry a timed-out download, because a connection too slow to finish inside the deadline won't finish on an immediate retry either. The steps below apply to both messages.
638
639A proxy or gateway can close a long transfer before it finishes, and the Claude Code binary is a large download.
640
641**What to do:**
642
643* Run `claude update` again. On an otherwise healthy network, the download usually succeeds on the next run. For the timed-out message, run it again from a faster or less throttled network.
644* If your network requires a proxy, set `HTTPS_PROXY` before running the installer or `claude update`. See [Check network connectivity](#check-network-connectivity).
645* If a corporate proxy keeps closing the transfer, ask your network team to allow the full download from `downloads.claude.ai`. See [Network access requirements](/docs/en/network-config#network-access-requirements).
646* Run `claude doctor` from your shell for installation diagnostics
647
508648### Wrong install command on Windows
509649
510650If you see `'irm' is not recognized`, `The token '&&' is not a valid statement separator`, `A parameter cannot be found that matches parameter name 'fsSL'`, or `'bash' is not recognized as the name of a cmdlet`, you copied the install command for a different shell or operating system. If the command prints the script's text instead of installing anything, you ran only part of it.
from line 783
6437832. **Close other processes** to free memory before installing.
644784
6457853. **Use a larger instance** if possible. Claude Code requires at least 4 GB of RAM.
786
787### Installation was killed before it could finish
788
789The install script reports when the `claude install` step is terminated by a signal. On Linux, exit code 137 means the process received SIGKILL, and on a low-memory host that's usually the kernel out-of-memory (OOM) killer. The script prints this explanation and exits with code 137:
790
791```text theme={null}
792Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
793Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.
794```
795
796For any other fatal signal, and for exit code 137 on macOS, the script prints `Installation was killed before it could finish (exit code <N>)` with the actual exit code and omits the out-of-memory explanation. The message comes from the install script macOS and Linux use, which also covers installs inside WSL; the native Windows install scripts never print it. Before v2.1.200, the script exited with only the shell's bare `Killed` line.
797
798**What to do:**
799
800* Stop other processes to free memory, then rerun the installer
801* Add swap space or move to a larger instance. See [Install killed on low-memory Linux servers](#install-killed-on-low-memory-linux-servers) for the swap-file commands.
646802
647803### Install hangs in Docker
648804
No line in this hunk matches that.