6 6
7> Discover solutions to common issues with Claude Code installation and usage.7> Discover solutions to common issues with Claude Code installation and usage.
8 8
9## Troubleshoot installation issues
10
11<Tip>
12 If you'd rather skip the terminal entirely, the [Claude Code Desktop app](/en/desktop-quickstart) lets you install and use Claude Code through a graphical interface. Download it for [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) or [Windows](https://claude.ai/api/desktop/win32/x64/exe/latest/redirect?utm_source=claude_code\&utm_medium=docs) and start coding without any command-line setup.
13</Tip>
14
15Find the error message or symptom you're seeing:
16
17| What you see | Solution |
18| :---------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |
19| `command not found: claude` or `'claude' is not recognized` | [Fix your PATH](#command-not-found-claude-after-installation) |
20| `syntax error near unexpected token '<'` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |
21| `curl: (56) Failure writing output to destination` | [Download script first, then run it](#curl-56-failure-writing-output-to-destination) |
22| `Killed` during install on Linux | [Add swap space for low-memory servers](#install-killed-on-low-memory-linux-servers) |
23| `TLS connect error` or `SSL/TLS secure channel` | [Update CA certificates](#tls-or-ssl-connection-errors) |
24| `Failed to fetch version` or can't reach download server | [Check network and proxy settings](#check-network-connectivity) |
25| `irm is not recognized` or `&& is not valid` | [Use the right command for your shell](#windows-irm-or--not-recognized) |
26| `Claude Code on Windows requires git-bash` | [Install or configure Git Bash](#windows-claude-code-on-windows-requires-git-bash) |
27| `Error loading shared library` | [Wrong binary variant for your system](#linux-wrong-binary-variant-installed-muslglibc-mismatch) |
28| `Illegal instruction` on Linux | [Architecture mismatch](#illegal-instruction-on-linux) |
29| `dyld: cannot load` or `Abort trap` on macOS | [Binary incompatibility](#dyld-cannot-load-on-macos) |
30| `Invoke-Expression: Missing argument in parameter list` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |
31| `App unavailable in region` | Claude Code is not available in your country. See [supported countries](https://www.anthropic.com/supported-countries). |
32| `unable to get local issuer certificate` | [Configure corporate CA certificates](#tls-or-ssl-connection-errors) |
33| `OAuth error` or `403 Forbidden` | [Fix authentication](#authentication-issues) |
34
35If your issue isn't listed, work through these diagnostic steps.
36
37## Debug installation problems
38
39### Check network connectivity
40
41The installer downloads from `storage.googleapis.com`. Verify you can reach it:
42
43```bash theme={null}
44curl -sI https://storage.googleapis.com
45```
46
47If this fails, your network may be blocking the connection. Common causes:
48
49* Corporate firewalls or proxies blocking Google Cloud Storage
50* Regional network restrictions: try a VPN or alternative network
51* TLS/SSL issues: update your system's CA certificates, or check if `HTTPS_PROXY` is configured
52
53If you're behind a corporate proxy, set `HTTPS_PROXY` and `HTTP_PROXY` to your proxy's address before installing. Ask your IT team for the proxy URL if you don't know it, or check your browser's proxy settings.
54
55This example sets both proxy variables, then runs the installer through your proxy:
56
57```bash theme={null}
58export HTTP_PROXY=http://proxy.example.com:8080
59export HTTPS_PROXY=http://proxy.example.com:8080
60curl -fsSL https://claude.ai/install.sh | bash
61```
62
63### Verify your PATH
64
65If 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.
66
67Check if the install directory is in your PATH by listing your PATH entries and filtering for `local/bin`:
68
69<Tabs>
70 <Tab title="macOS/Linux">
71 ```bash theme={null}
72 echo $PATH | tr ':' '\n' | grep local/bin
73 ```
74
75 If there's no output, the directory is missing. Add it to your shell configuration:
76
77 ```bash theme={null}
78 # Zsh (macOS default)
79 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
80 source ~/.zshrc
81
82 # Bash (Linux default)
83 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
84 source ~/.bashrc
85 ```
86
87 Alternatively, close and reopen your terminal.
88
89 Verify the fix worked:
90
91 ```bash theme={null}
92 claude --version
93 ```
94 </Tab>
95
96 <Tab title="Windows PowerShell">
97 ```powershell theme={null}
98 $env:PATH -split ';' | Select-String 'local\\bin'
99 ```
100
101 If there's no output, add the install directory to your User PATH:
102
103 ```powershell theme={null}
104 $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
105 [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
106 ```
107
108 Restart your terminal for the change to take effect.
109
110 Verify the fix worked:
111
112 ```powershell theme={null}
113 claude --version
114 ```
115 </Tab>
116
117 <Tab title="Windows CMD">
118 ```batch theme={null}
119 echo %PATH% | findstr /i "local\bin"
120 ```
121
122 If there's no output, open System Settings, go to Environment Variables, and add `%USERPROFILE%\.local\bin` to your User PATH variable. Restart your terminal.
123
124 Verify the fix worked:
125
126 ```batch theme={null}
127 claude --version
128 ```
129 </Tab>
130</Tabs>
131
132### Check for conflicting installations
133
134Multiple Claude Code installations can cause version mismatches or unexpected behavior. Check what's installed:
135
136<Tabs>
137 <Tab title="macOS/Linux">
138 List all `claude` binaries found in your PATH:
139
140 ```bash theme={null}
141 which -a claude
142 ```
143
144 Check whether the native installer and npm versions are present:
145
146 ```bash theme={null}
147 ls -la ~/.local/bin/claude
148 ```
149
150 ```bash theme={null}
151 ls -la ~/.claude/local/
152 ```
153
154 ```bash theme={null}
155 npm -g ls @anthropic-ai/claude-code 2>/dev/null
156 ```
157 </Tab>
158
159 <Tab title="Windows PowerShell">
160 ```powershell theme={null}
161 where.exe claude
162 Test-Path "$env:LOCALAPPDATA\Claude Code\claude.exe"
163 ```
164 </Tab>
165</Tabs>
166
167If you find multiple installations, keep only one. The native install at `~/.local/bin/claude` is recommended. Remove any extra installations:
168
169Uninstall an npm global install:
170
171```bash theme={null}
172npm uninstall -g @anthropic-ai/claude-code
173```
174
175Remove a Homebrew install on macOS:
176
177```bash theme={null}
178brew uninstall --cask claude-code
179```
180
181### Check directory permissions
182
183The installer needs write access to `~/.local/bin/` and `~/.claude/`. If installation fails with permission errors, check whether these directories are writable:
184
185```bash theme={null}
186test -w ~/.local/bin && echo "writable" || echo "not writable"
187test -w ~/.claude && echo "writable" || echo "not writable"
188```
189
190If either directory isn't writable, create the install directory and set your user as the owner:
191
192```bash theme={null}
193sudo mkdir -p ~/.local/bin
194sudo chown -R $(whoami) ~/.local
195```
196
197### Verify the binary works
198
199If `claude` is installed but crashes or hangs on startup, run these checks to narrow down the cause.
200
201Confirm the binary exists and is executable:
202
203```bash theme={null}
204ls -la $(which claude)
205```
206
207On Linux, check for missing shared libraries. If `ldd` shows missing libraries, you may need to install system packages. On Alpine Linux and other musl-based distributions, see [Alpine Linux setup](/en/setup#alpine-linux-and-musl-based-distributions).
208
209```bash theme={null}
210ldd $(which claude) | grep "not found"
211```
212
213Run a quick sanity check that the binary can execute:
214
215```bash theme={null}
216claude --version
217```
218
9## Common installation issues219## Common installation issues
10 220
221These are the most frequently encountered installation problems and their solutions.
222
223### Install script returns HTML instead of a shell script
224
225When running the install command, you may see one of these errors:
226
227```
228bash: line 1: syntax error near unexpected token `<'
229bash: line 1: `<!DOCTYPE html>'
230```
231
232On PowerShell, the same problem appears as:
233
234```
235Invoke-Expression: Missing argument in parameter list.
236```
237
238This means the install URL returned an HTML page 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).
239
240Otherwise, this can happen due to network issues, regional routing, or a temporary service disruption.
241
242**Solutions:**
243
2441. **Use an alternative install method**:
245
246 On macOS or Linux, install via Homebrew:
247
248 ```bash theme={null}
249 brew install --cask claude-code
250 ```
251
252 On Windows, install via WinGet:
253
254 ```powershell theme={null}
255 winget install Anthropic.ClaudeCode
256 ```
257
2582. **Retry after a few minutes**: the issue is often temporary. Wait and try the original command again.
259
260### `command not found: claude` after installation
261
262The install finished but `claude` doesn't work. The exact error varies by platform:
263
264| Platform | Error message |
265| :---------- | :--------------------------------------------------------------------- |
266| macOS | `zsh: command not found: claude` |
267| Linux | `bash: claude: command not found` |
268| Windows CMD | `'claude' is not recognized as an internal or external command` |
269| PowerShell | `claude : The term 'claude' is not recognized as the name of a cmdlet` |
270
271This means the install directory isn't in your shell's search path. See [Verify your PATH](#verify-your-path) for the fix on each platform.
272
273### `curl: (56) Failure writing output to destination`
274
275The `curl ... | bash` command downloads the script and passes it directly to Bash for execution using a pipe (`|`). This error means the connection broke before the script finished downloading. Common causes include network interruptions, the download being blocked mid-stream, or system resource limits.
276
277**Solutions:**
278
2791. **Check network stability**: Claude Code binaries are hosted on Google Cloud Storage. Test that you can reach it:
280 ```bash theme={null}
281 curl -fsSL https://storage.googleapis.com -o /dev/null
282 ```
283 If the command completes silently, your connection is fine and the issue is likely intermittent. Retry the install command. If you see an error, your network may be blocking the download.
284
2852. **Try an alternative install method**:
286
287 On macOS or Linux:
288
289 ```bash theme={null}
290 brew install --cask claude-code
291 ```
292
293 On Windows:
294
295 ```powershell theme={null}
296 winget install Anthropic.ClaudeCode
297 ```
298
299### TLS or SSL connection errors
300
301Errors like `curl: (35) TLS connect error`, `schannel: next InitializeSecurityContext failed`, or PowerShell's `Could not establish trust relationship for the SSL/TLS secure channel` indicate TLS handshake failures.
302
303**Solutions:**
304
3051. **Update your system CA certificates**:
306
307 On Ubuntu/Debian:
308
309 ```bash theme={null}
310 sudo apt-get update && sudo apt-get install ca-certificates
311 ```
312
313 On macOS via Homebrew:
314
315 ```bash theme={null}
316 brew install ca-certificates
317 ```
318
3192. **On Windows, enable TLS 1.2** in PowerShell before running the installer:
320 ```powershell theme={null}
321 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
322 irm https://claude.ai/install.ps1 | iex
323 ```
324
3253. **Check for proxy or firewall interference**: corporate proxies that perform TLS inspection can cause these errors, including `unable to get local issuer certificate`. Set `NODE_EXTRA_CA_CERTS` to your corporate CA certificate bundle:
326 ```bash theme={null}
327 export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
328 ```
329 Ask your IT team for the certificate file if you don't have it. You can also try on a direct connection to confirm the proxy is the cause.
330
331### `Failed to fetch version from storage.googleapis.com`
332
333The installer couldn't reach the download server. This typically means `storage.googleapis.com` is blocked on your network.
334
335**Solutions:**
336
3371. **Test connectivity directly**:
338 ```bash theme={null}
339 curl -sI https://storage.googleapis.com
340 ```
341
3422. **If behind a proxy**, set `HTTPS_PROXY` so the installer can route through it. See [proxy configuration](/en/network-config#proxy-configuration) for details.
343 ```bash theme={null}
344 export HTTPS_PROXY=http://proxy.example.com:8080
345 curl -fsSL https://claude.ai/install.sh | bash
346 ```
347
3483. **If on a restricted network**, try a different network or VPN, or use an alternative install method:
349
350 On macOS or Linux:
351
352 ```bash theme={null}
353 brew install --cask claude-code
354 ```
355
356 On Windows:
357
358 ```powershell theme={null}
359 winget install Anthropic.ClaudeCode
360 ```
361
362### Windows: `irm` or `&&` not recognized
363
364If you see `'irm' is not recognized` or `The token '&&' is not valid`, you're running the wrong command for your shell.
365
366* **`irm` not recognized**: you're in CMD, not PowerShell. You have two options:
367
368 Open PowerShell by searching for "PowerShell" in the Start menu, then run the original install command:
369
370 ```powershell theme={null}
371 irm https://claude.ai/install.ps1 | iex
372 ```
373
374 Or stay in CMD and use the CMD installer instead:
375
376 ```batch theme={null}
377 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
378 ```
379
380* **`&&` not valid**: you're in PowerShell but ran the CMD installer command. Use the PowerShell installer:
381 ```powershell theme={null}
382 irm https://claude.ai/install.ps1 | iex
383 ```
384
385### Install killed on low-memory Linux servers
386
387If you see `Killed` during installation on a VPS or cloud instance:
388
389```
390Setting up Claude Code...
391Installing Claude Code native build latest...
392bash: line 142: 34803 Killed "$binary_path" install ${TARGET:+"$TARGET"}
393```
394
395The Linux OOM killer terminated the process because the system ran out of memory. Claude Code requires at least 4 GB of available RAM.
396
397**Solutions:**
398
3991. **Add swap space** if your server has limited RAM. Swap uses disk space as overflow memory, letting the install complete even with low physical RAM.
400
401 Create a 2 GB swap file and enable it:
402
403 ```bash theme={null}
404 sudo fallocate -l 2G /swapfile
405 sudo chmod 600 /swapfile
406 sudo mkswap /swapfile
407 sudo swapon /swapfile
408 ```
409
410 Then retry the installation:
411
412 ```bash theme={null}
413 curl -fsSL https://claude.ai/install.sh | bash
414 ```
415
4162. **Close other processes** to free memory before installing.
417
4183. **Use a larger instance** if possible. Claude Code requires at least 4 GB of RAM.
419
420### Install hangs in Docker
421
422When installing Claude Code in a Docker container, installing as root into `/` can cause hangs.
423
424**Solutions:**
425
4261. **Set a working directory** before running the installer. When run from `/`, the installer scans the entire filesystem, which causes excessive memory usage. Setting `WORKDIR` limits the scan to a small directory:
427 ```dockerfile theme={null}
428 WORKDIR /tmp
429 RUN curl -fsSL https://claude.ai/install.sh | bash
430 ```
431
4322. **Increase Docker memory limits** if using Docker Desktop:
433 ```bash theme={null}
434 docker build --memory=4g .
435 ```
436
437### Windows: Claude Desktop overrides `claude` CLI command
438
439If you installed an older version of Claude Desktop, it may register a `Claude.exe` in the `WindowsApps` directory that takes PATH priority over Claude Code CLI. Running `claude` opens the Desktop app instead of the CLI.
440
441Update Claude Desktop to the latest version to fix this issue.
442
443### Windows: "Claude Code on Windows requires git-bash"
444
445Claude Code on native Windows needs [Git for Windows](https://git-scm.com/downloads/win), which includes Git Bash.
446
447**If Git is not installed**, download and install it from [git-scm.com/downloads/win](https://git-scm.com/downloads/win). During setup, select "Add to PATH." Restart your terminal after installing.
448
449**If Git is already installed** but Claude Code still can't find it, set the path in your [settings.json file](/en/settings):
450
451```json theme={null}
452{
453 "env": {
454 "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
455 }
456}
457```
458
459If your Git is installed somewhere else, find the path by running `where.exe git` in PowerShell and use the `bin\bash.exe` path from that directory.
460
461### Linux: wrong binary variant installed (musl/glibc mismatch)
462
463If you see errors about missing shared libraries like `libstdc++.so.6` or `libgcc_s.so.1` after installation, the installer may have downloaded the wrong binary variant for your system.
464
465```
466Error loading shared library libstdc++.so.6: No such file or directory
467```
468
469This can happen on glibc-based systems that have musl cross-compilation packages installed, causing the installer to misdetect the system as musl.
470
471**Solutions:**
472
4731. **Check which libc your system uses**:
474 ```bash theme={null}
475 ldd /bin/ls | head -1
476 ```
477 If it shows `linux-vdso.so` or references to `/lib/x86_64-linux-gnu/`, you're on glibc. If it shows `musl`, you're on musl.
478
4792. **If you're on glibc but got the musl binary**, remove the installation and reinstall. You can also manually download the correct binary from the GCS bucket at `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json`. File a [GitHub issue](https://github.com/anthropics/claude-code/issues) with the output of `ldd /bin/ls` and `ls /lib/libc.musl*`.
480
4813. **If you're actually on musl** (Alpine Linux), install the required packages:
482 ```bash theme={null}
483 apk add libgcc libstdc++ ripgrep
484 ```
485
486### `Illegal instruction` on Linux
487
488If the installer prints `Illegal instruction` instead of the OOM `Killed` message, the downloaded binary doesn't match your CPU architecture. This commonly happens on ARM servers that receive an x86 binary, or on older CPUs that lack required instruction sets.
489
490```
491bash: line 142: 2238232 Illegal instruction "$binary_path" install ${TARGET:+"$TARGET"}
492```
493
494**Solutions:**
495
4961. **Verify your architecture**:
497 ```bash theme={null}
498 uname -m
499 ```
500 `x86_64` means 64-bit Intel/AMD, `aarch64` means ARM64. If the binary doesn't match, [file a GitHub issue](https://github.com/anthropics/claude-code/issues) with the output.
501
5022. **Try an alternative install method** while the architecture issue is resolved:
503 ```bash theme={null}
504 brew install --cask claude-code
505 ```
506
507### `dyld: cannot load` on macOS
508
509If you see `dyld: cannot load` or `Abort trap: 6` during installation, the binary is incompatible with your macOS version or hardware.
510
511```
512dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
513Abort trap: 6
514```
515
516**Solutions:**
517
5181. **Check your macOS version**: Claude Code requires macOS 13.0 or later. Open the Apple menu and select About This Mac to check your version.
519
5202. **Update macOS** if you're on an older version. The binary uses load commands that older macOS versions don't support.
521
5223. **Try Homebrew** as an alternative install method:
523 ```bash theme={null}
524 brew install --cask claude-code
525 ```
526
11### Windows installation issues: errors in WSL527### Windows installation issues: errors in WSL
12 528
13You might encounter the following issues in WSL:529You might encounter the following issues in WSL:
14 530
15**OS/platform detection issues**: If you receive an error during installation, WSL may be using Windows `npm`. Try:531**OS/platform detection issues**: if you receive an error during installation, WSL may be using Windows `npm`. Try:
16 532
17* Run `npm config set os linux` before installation533* Run `npm config set os linux` before installation
18* Install with `npm install -g @anthropic-ai/claude-code --force --no-os-check` (Do NOT use `sudo`)534* Install with `npm install -g @anthropic-ai/claude-code --force --no-os-check`. Do not use `sudo`.
19 535
20**Node not found errors**: If you see `exec: node: not found` when running `claude`, your WSL environment may be using a Windows installation of Node.js. You can confirm this with `which npm` and `which node`, which should point to Linux paths starting with `/usr/` rather than `/mnt/c/`. To fix this, try installing Node via your Linux distribution's package manager or via [`nvm`](https://github.com/nvm-sh/nvm).536**Node not found errors**: if you see `exec: node: not found` when running `claude`, your WSL environment may be using a Windows installation of Node.js. You can confirm this with `which npm` and `which node`, which should point to Linux paths starting with `/usr/` rather than `/mnt/c/`. To fix this, try installing Node via your Linux distribution's package manager or via [`nvm`](https://github.com/nvm-sh/nvm).
21 537
22**nvm version conflicts**: If you have nvm installed in both WSL and Windows, you may experience version conflicts when switching Node versions in WSL. This happens because WSL imports the Windows PATH by default, causing Windows nvm/npm to take priority over the WSL installation.538**nvm version conflicts**: if you have nvm installed in both WSL and Windows, you may experience version conflicts when switching Node versions in WSL. This happens because WSL imports the Windows PATH by default, causing Windows nvm/npm to take priority over the WSL installation.
23 539
24You can identify this issue by:540You can identify this issue by:
25 541
54```570```
55 571
56<Warning>572<Warning>
57 Avoid disabling Windows PATH importing (`appendWindowsPath = false`) as this breaks the ability to call Windows executables from WSL. Similarly, avoid uninstalling Node.js from Windows if you use it for Windows development.573 Avoid disabling Windows PATH importing via `appendWindowsPath = false` as this breaks the ability to call Windows executables from WSL. Similarly, avoid uninstalling Node.js from Windows if you use it for Windows development.
58</Warning>574</Warning>
59 575
60### WSL2 sandbox setup576### WSL2 sandbox setup
77 593
78WSL1 does not support sandboxing. If you see "Sandboxing requires WSL2", you need to upgrade to WSL2 or run Claude Code without sandboxing.594WSL1 does not support sandboxing. If you see "Sandboxing requires WSL2", you need to upgrade to WSL2 or run Claude Code without sandboxing.
79 595
80### Linux and Mac installation issues: permission or command not found errors596### Permission errors during installation
81
82When installing Claude Code with npm, `PATH` problems may prevent access to `claude`.
83You may also encounter permission errors if your npm global prefix is not user writable (for example, `/usr`, or `/usr/local`).
84 597
85#### Recommended solution: Native Claude Code installation598If the native installer fails with permission errors, the target directory may not be writable. See [Check directory permissions](#check-directory-permissions).
86 599
87Claude Code has a native installation that doesn't depend on npm or Node.js.600If you previously installed with npm and are hitting npm-specific permission errors, switch to the native installer:
88
89Use the following command to run the native installer.
90
91**macOS, Linux, WSL:**
92 601
93```bash theme={null}602```bash theme={null}
94# Install stable version (default)
95curl -fsSL https://claude.ai/install.sh | bash603curl -fsSL https://claude.ai/install.sh | bash
96
97# Install latest version
98curl -fsSL https://claude.ai/install.sh | bash -s latest
99
100# Install specific version number
101curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
102```604```
103 605
104**Windows PowerShell:**606## Permissions and authentication
105
106```powershell theme={null}
107# Install stable version (default)
108irm https://claude.ai/install.ps1 | iex
109
110# Install latest version
111& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest
112 607
113# Install specific version number608These sections address login failures, token issues, and permission prompt behavior.
114& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
115 609
116```610### Repeated permission prompts
117 611
118This command installs the appropriate build of Claude Code for your operating system and architecture and adds a symlink to the installation at `~/.local/bin/claude` (or `%USERPROFILE%\.local\bin\claude.exe` on Windows).612If you find yourself repeatedly approving the same commands, you can allow specific tools
613to run without approval using the `/permissions` command. See [Permissions docs](/en/permissions#manage-permissions).
119 614
120<Tip>615### Authentication issues
121 Make sure that you have the installation directory in your system PATH.
122</Tip>
123 616
124### Windows: "Claude Code on Windows requires git-bash"617If you're experiencing authentication problems:
125 618
126Claude Code on native Windows requires [Git for Windows](https://git-scm.com/downloads/win) which includes Git Bash. If Git is installed but not detected:6191. Run `/logout` to sign out completely
6202. Close Claude Code
6213. Restart with `claude` and complete the authentication process again
127 622
1281. Set the path explicitly in PowerShell before running Claude:623If the browser doesn't open automatically during login, press `c` to copy the OAuth URL to your clipboard, then paste it into your browser manually.
129 ```powershell theme={null}
130 $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"
131 ```
132 624
1332. Or add it to your system environment variables permanently through System Properties → Environment Variables.625### OAuth error: Invalid code
134 626
135If Git is installed in a non-standard location, adjust the path accordingly.627If you see `OAuth error: Invalid code. Please make sure the full code was copied`, the login code expired or was truncated during copy-paste.
136 628
137### Windows: "installMethod is native, but claude command not found"629**Solutions:**
138 630
139If you see this error after installation, the `claude` command isn't in your PATH. Add it manually:631* Press Enter to retry and complete the login quickly after the browser opens
632* Type `c` to copy the full URL if the browser doesn't open automatically
633* If using a remote/SSH session, the browser may open on the wrong machine. Copy the URL displayed in the terminal and open it in your local browser instead.
140 634
141<Steps>635### 403 Forbidden after login
142 <Step title="Open Environment Variables">
143 Press `Win + R`, type `sysdm.cpl`, and press Enter. Click **Advanced** → **Environment Variables**.
144 </Step>
145 636
146 <Step title="Edit User PATH">637If you see `API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}` after logging in:
147 Under "User variables", select **Path** and click **Edit**. Click **New** and add:
148 638
149 ```639* **Claude Pro/Max users**: verify your subscription is active at [claude.ai/settings](https://claude.ai/settings)
150 %USERPROFILE%\.local\bin640* **Console users**: confirm your account has the "Claude Code" or "Developer" role assigned by your admin
151 ```641* **Behind a proxy**: corporate proxies can interfere with API requests. See [network configuration](/en/network-config) for proxy setup.
152 </Step>
153 642
154 <Step title="Restart your terminal">643### OAuth login fails in WSL2
155 Close and reopen PowerShell or CMD for changes to take effect.
156 </Step>
157</Steps>
158 644
159Verify installation:645Browser-based login in WSL2 may fail if WSL can't open your Windows browser. Set the `BROWSER` environment variable:
160 646
161```bash theme={null}647```bash theme={null}
162claude doctor # Check installation health648export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
649claude
163```650```
164 651
165## Permissions and authentication652Or copy the URL manually: when the login prompt appears, press `c` to copy the OAuth URL, then paste it into your Windows browser.
166
167### Repeated permission prompts
168 653
169If you find yourself repeatedly approving the same commands, you can allow specific tools654### "Not logged in" or token expired
170to run without approval using the `/permissions` command. See [Permissions docs](/en/permissions#manage-permissions).
171 655
172### Authentication issues656If Claude Code prompts you to log in again after a session, your OAuth token may have expired.
173 657
174If you're experiencing authentication problems:658Run `/login` to re-authenticate. If this happens frequently, check that your system clock is accurate, as token validation depends on correct timestamps.
175
1761. Run `/logout` to sign out completely
1772. Close Claude Code
1783. Restart with `claude` and complete the authentication process again
179
180If the browser doesn't open automatically during login, press `c` to copy the OAuth URL to your clipboard, then paste it into your browser manually.
181
182If problems persist, try:
183
184```bash theme={null}
185rm -rf ~/.config/claude-code/auth.json
186claude
187```
188
189This removes your stored authentication information and forces a clean login.
190 659
191## Configuration file locations660## Configuration file locations
192 661
226 695
227## Performance and stability696## Performance and stability
228 697
698These sections cover issues related to resource usage, responsiveness, and search behavior.
699
229### High CPU or memory usage700### High CPU or memory usage
230 701
231Claude Code is designed to work with most development environments, but may consume significant resources when processing large codebases. If you're experiencing performance issues:702Claude Code is designed to work with most development environments, but may consume significant resources when processing large codebases. If you're experiencing performance issues:
266 737
267### Slow or incomplete search results on WSL738### Slow or incomplete search results on WSL
268 739
269Disk read performance penalties when [working across file systems on WSL](https://learn.microsoft.com/en-us/windows/wsl/filesystems) may result in fewer-than-expected matches (but not a complete lack of search functionality) when using Claude Code on WSL.740Disk read performance penalties when [working across file systems on WSL](https://learn.microsoft.com/en-us/windows/wsl/filesystems) may result in fewer-than-expected matches when using Claude Code on WSL. Search still functions, but returns fewer results than on a native filesystem.
270 741
271<Note>742<Note>
272 `/doctor` will show Search as OK in this case.743 `/doctor` will show Search as OK in this case.
274 745
275**Solutions:**746**Solutions:**
276 747
2771. **Submit more specific searches**: Reduce the number of files searched by specifying directories or file types: "Search for JWT validation logic in the auth-service package" or "Find use of md5 hash in JS files".7481. **Submit more specific searches**: reduce the number of files searched by specifying directories or file types: "Search for JWT validation logic in the auth-service package" or "Find use of md5 hash in JS files".
278 749
2792. **Move project to Linux filesystem**: If possible, ensure your project is located on the Linux filesystem (`/home/`) rather than the Windows filesystem (`/mnt/c/`).7502. **Move project to Linux filesystem**: if possible, ensure your project is located on the Linux filesystem (`/home/`) rather than the Windows filesystem (`/mnt/c/`).
280 751
2813. **Use native Windows instead**: Consider running Claude Code natively on Windows instead of through WSL, for better file system performance.7523. **Use native Windows instead**: consider running Claude Code natively on Windows instead of through WSL, for better file system performance.
282 753
283## IDE integration issues754## IDE integration issues
284 755
756If Claude Code does not connect to your IDE or behaves unexpectedly within an IDE terminal, try the solutions below.
757
285### JetBrains IDE not detected on WSL2758### JetBrains IDE not detected on WSL2
286 759
287If you're using Claude Code on WSL2 with JetBrains IDEs and getting "No available IDEs detected" errors, this is likely due to WSL2's networking configuration or Windows Firewall blocking the connection.760If you're using Claude Code on WSL2 with JetBrains IDEs and getting "No available IDEs detected" errors, this is likely due to WSL2's networking configuration or Windows Firewall blocking the connection.
2951. Find your WSL2 IP address:7681. Find your WSL2 IP address:
296 ```bash theme={null}769 ```bash theme={null}
297 wsl hostname -I770 wsl hostname -I
298 # Example output: 172.21.123.456771 # Example output: 172.21.123.45
299 ```772 ```
300 773
3012. Open PowerShell as Administrator and create a firewall rule:7742. Open PowerShell as Administrator and create a firewall rule:
302 ```powershell theme={null}775 ```powershell theme={null}
303 New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16776 New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
304 ```777 ```
305 (Adjust the IP range based on your WSL2 subnet from step 1)778 Adjust the IP range based on your WSL2 subnet from step 1.
306 779
3073. Restart both your IDE and Claude Code7803. Restart both your IDE and Claude Code
308 781
321 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.794 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.
322</Note>795</Note>
323 796
324For additional JetBrains configuration tips, see our [JetBrains IDE guide](/en/jetbrains#plugin-settings).797For additional JetBrains configuration tips, see the [JetBrains IDE guide](/en/jetbrains#plugin-settings).
325 798
326### Reporting Windows IDE integration issues (both native and WSL)799### Report Windows IDE integration issues
327 800
328If you're experiencing IDE integration problems on Windows, [create an issue](https://github.com/anthropics/claude-code/issues) with the following information:801If you're experiencing IDE integration problems on Windows, [create an issue](https://github.com/anthropics/claude-code/issues) with the following information:
329 802
330* Environment type: native Windows (Git Bash) or WSL1/WSL2803* Environment type: native Windows (Git Bash) or WSL1/WSL2
331* WSL networking mode (if applicable): NAT or mirrored804* WSL networking mode, if applicable: NAT or mirrored
332* IDE name and version805* IDE name and version
333* Claude Code extension/plugin version806* Claude Code extension/plugin version
334* Shell type: Bash, Zsh, PowerShell, etc.807* Shell type: Bash, Zsh, PowerShell, etc.
335 808
336### Escape key not working in JetBrains (IntelliJ, PyCharm, etc.) terminals809### Escape key not working in JetBrains IDE terminals
337 810
338If you're using Claude Code in JetBrains terminals and the `Esc` key doesn't interrupt the agent as expected, this is likely due to a keybinding clash with JetBrains' default shortcuts.811If you're using Claude Code in JetBrains terminals and the `Esc` key doesn't interrupt the agent as expected, this is likely due to a keybinding clash with JetBrains' default shortcuts.
339 812
375 848
376**Solutions:**849**Solutions:**
377 850
3781. **Ask Claude to add language tags**: Request "Add appropriate language tags to all code blocks in this markdown file."8511. **Ask Claude to add language tags**: request "Add appropriate language tags to all code blocks in this markdown file."
379 852
3802. **Use post-processing hooks**: Set up automatic formatting hooks to detect and add missing language tags. See [Auto-format code after edits](/en/hooks-guide#auto-format-code-after-edits) for an example of a PostToolUse formatting hook.8532. **Use post-processing hooks**: set up automatic formatting hooks to detect and add missing language tags. See [Auto-format code after edits](/en/hooks-guide#auto-format-code-after-edits) for an example of a PostToolUse formatting hook.
381 854
3823. **Manual verification**: After generating markdown files, review them for proper code block formatting and request corrections if needed.8553. **Manual verification**: after generating markdown files, review them for proper code block formatting and request corrections if needed.
383 856
384### Inconsistent spacing and formatting857### Inconsistent spacing and formatting
385 858
387 860
388**Solutions:**861**Solutions:**
389 862
3901. **Request formatting corrections**: Ask Claude to "Fix spacing and formatting issues in this markdown file."8631. **Request formatting corrections**: ask Claude to "Fix spacing and formatting issues in this markdown file."
391 864
3922. **Use formatting tools**: Set up hooks to run markdown formatters like `prettier` or custom formatting scripts on generated markdown files.8652. **Use formatting tools**: set up hooks to run markdown formatters like `prettier` or custom formatting scripts on generated markdown files.
393 866
3943. **Specify formatting preferences**: Include formatting requirements in your prompts or project [memory](/en/memory) files.8673. **Specify formatting preferences**: include formatting requirements in your prompts or project [memory](/en/memory) files.
395 868
396### Best practices for markdown generation869### Reduce markdown formatting issues
397 870
398To minimize formatting issues:871To minimize formatting issues:
399 872
400* **Be explicit in requests**: Ask for "properly formatted markdown with language-tagged code blocks"873* **Be explicit in requests**: ask for "properly formatted markdown with language-tagged code blocks"
401* **Use project conventions**: Document your preferred markdown style in [`CLAUDE.md`](/en/memory)874* **Use project conventions**: document your preferred markdown style in [`CLAUDE.md`](/en/memory)
402* **Set up validation hooks**: Use post-processing hooks to automatically verify and fix common formatting issues875* **Set up validation hooks**: use post-processing hooks to automatically verify and fix common formatting issues
403 876
404## Getting more help877## Get more help
405 878
406If you're experiencing issues not covered here:879If you're experiencing issues not covered here:
407 880
