4 4
5# Troubleshooting5# Troubleshooting
6 6
7> Discover solutions to common issues with Claude Code installation and usage.7> Fix high CPU or memory usage, hangs, auto-compact thrashing, and search problems in Claude Code, and find the right page for other issues.
8 8
9## Troubleshoot installation issues9This page covers performance, stability, and search problems once Claude Code is running. For other issues, start with the page that matches where you're stuck:
10 10
11<Tip>11| Symptom | Go to |
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.com/download?utm_source=claude_code\&utm_medium=docs) and start coding without any command-line setup.12| :------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------- |
13</Tip>13| `command not found`, install fails, PATH issues, `EACCES`, TLS errors | [Troubleshoot installation and login](/en/troubleshoot-install) |
14| Login loops, OAuth errors, `403 Forbidden`, "organization disabled", Bedrock/Vertex/Foundry credentials | [Troubleshoot installation and login](/en/troubleshoot-install#login-and-authentication) |
15| Settings not applying, hooks not firing, MCP servers not loading | [Debug your configuration](/en/debug-your-config) |
16| `API Error: 5xx`, `529 Overloaded`, `429`, request validation errors | [Error reference](/en/errors) |
17| `model not found` or `you may not have access to it` | [Error reference](/en/errors#theres-an-issue-with-the-selected-model) |
18| VS Code extension not connecting or detecting Claude | [VS Code integration](/en/vs-code#fix-common-issues) |
19| JetBrains plugin or IDE not detected | [JetBrains integration](/en/jetbrains#troubleshooting) |
20| High CPU or memory, slow responses, hangs, search not finding files | [Performance and stability](#performance-and-stability) below |
14 21
15Find the error message or symptom you're seeing:22If you're not sure which applies, run `/doctor` inside Claude Code for an automated check of your installation, settings, MCP servers, and context usage. If `claude` won't start at all, run `claude doctor` from your shell instead.
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-wrong-install-command) |
26| `'bash' is not recognized as the name of a cmdlet` | [Use the Windows installer command](#windows-wrong-install-command) |
27| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell` | [Install a shell](#windows-claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell) |
28| `Claude Code does not support 32-bit Windows` | [Open Windows PowerShell, not the x86 entry](#windows-claude-code-does-not-support-32-bit-windows) |
29| `Error loading shared library` | [Wrong binary variant for your system](#linux-wrong-binary-variant-installed-musl/glibc-mismatch) |
30| `Illegal instruction` on Linux | [Architecture mismatch](#illegal-instruction-on-linux) |
31| `dyld: cannot load`, `dyld: Symbol not found`, or `Abort trap` on macOS | [Binary incompatibility](#dyld-cannot-load-on-macos) |
32| `Invoke-Expression: Missing argument in parameter list` | [Install script returns HTML](#install-script-returns-html-instead-of-a-shell-script) |
33| `App unavailable in region` | Claude Code is not available in your country. See [supported countries](https://www.anthropic.com/supported-countries). |
34| `unable to get local issuer certificate` | [Configure corporate CA certificates](#tls-or-ssl-connection-errors) |
35| `OAuth error` or `403 Forbidden` | [Fix authentication](#authentication-issues) |
36| `API Error: 500`, `529 Overloaded`, `429`, or other 4xx and 5xx errors not listed above | See the [Error reference](/en/errors) |
37
38If your issue isn't listed, work through these diagnostic steps.
39
40## Debug installation problems
41
42### Check network connectivity
43
44The installer downloads from `downloads.claude.ai`. Verify you can reach it:
45
46```bash theme={null}
47curl -sI https://downloads.claude.ai
48```
49
50If this fails, your network may be blocking the connection. Common causes:
51
52* Corporate firewalls or proxies blocking `downloads.claude.ai`
53* Regional network restrictions: try a VPN or alternative network
54* TLS/SSL issues: update your system's CA certificates, or check if `HTTPS_PROXY` is configured
55
56If 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.
57
58This example sets both proxy variables, then runs the installer through your proxy:
59
60```bash theme={null}
61export HTTP_PROXY=http://proxy.example.com:8080
62export HTTPS_PROXY=http://proxy.example.com:8080
63curl -fsSL https://claude.ai/install.sh | bash
64```
65
66### Verify your PATH
67
68If 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.
69
70Check if the install directory is in your PATH by listing your PATH entries and filtering for `local/bin`:
71
72<Tabs>
73 <Tab title="macOS/Linux">
74 ```bash theme={null}
75 echo $PATH | tr ':' '\n' | grep local/bin
76 ```
77
78 If there's no output, the directory is missing. Add it to your shell configuration:
79
80 ```bash theme={null}
81 # Zsh (macOS default)
82 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
83 source ~/.zshrc
84
85 # Bash (Linux default)
86 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
87 source ~/.bashrc
88 ```
89
90 Alternatively, close and reopen your terminal.
91
92 Verify the fix worked:
93
94 ```bash theme={null}
95 claude --version
96 ```
97 </Tab>
98
99 <Tab title="Windows PowerShell">
100 ```powershell theme={null}
101 $env:PATH -split ';' | Select-String 'local\\bin'
102 ```
103
104 If there's no output, add the install directory to your User PATH:
105
106 ```powershell theme={null}
107 $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
108 [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
109 ```
110
111 Restart your terminal for the change to take effect.
112
113 Verify the fix worked:
114
115 ```powershell theme={null}
116 claude --version
117 ```
118 </Tab>
119
120 <Tab title="Windows CMD">
121 ```batch theme={null}
122 echo %PATH% | findstr /i "local\bin"
123 ```
124
125 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.
126
127 Verify the fix worked:
128
129 ```batch theme={null}
130 claude --version
131 ```
132 </Tab>
133</Tabs>
134
135### Check for conflicting installations
136
137Multiple Claude Code installations can cause version mismatches or unexpected behavior. Check what's installed:
138
139<Tabs>
140 <Tab title="macOS/Linux">
141 List all `claude` binaries found in your PATH:
142
143 ```bash theme={null}
144 which -a claude
145 ```
146
147 Check whether the native installer and npm versions are present:
148
149 ```bash theme={null}
150 ls -la ~/.local/bin/claude
151 ```
152
153 ```bash theme={null}
154 ls -la ~/.claude/local/
155 ```
156
157 ```bash theme={null}
158 npm -g ls @anthropic-ai/claude-code 2>/dev/null
159 ```
160 </Tab>
161
162 <Tab title="Windows PowerShell">
163 ```powershell theme={null}
164 where.exe claude
165 Test-Path "$env:LOCALAPPDATA\Claude Code\claude.exe"
166 ```
167 </Tab>
168</Tabs>
169
170If you find multiple installations, keep only one. The native install at `~/.local/bin/claude` is recommended. Remove any extra installations:
171
172Uninstall an npm global install:
173
174```bash theme={null}
175npm uninstall -g @anthropic-ai/claude-code
176```
177
178Remove a Homebrew install on macOS (use `claude-code@latest` if you installed that cask):
179
180```bash theme={null}
181brew uninstall --cask claude-code
182```
183
184### Check directory permissions
185
186The installer needs write access to `~/.local/bin/` and `~/.claude/`. If installation fails with permission errors, check whether these directories are writable:
187
188```bash theme={null}
189test -w ~/.local/bin && echo "writable" || echo "not writable"
190test -w ~/.claude && echo "writable" || echo "not writable"
191```
192
193If either directory isn't writable, create the install directory and set your user as the owner:
194
195```bash theme={null}
196sudo mkdir -p ~/.local/bin
197sudo chown -R $(whoami) ~/.local
198```
199
200### Verify the binary works
201
202If `claude` is installed but crashes or hangs on startup, run these checks to narrow down the cause.
203
204Confirm the binary exists and is executable:
205
206```bash theme={null}
207ls -la $(which claude)
208```
209
210On 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).
211
212```bash theme={null}
213ldd $(which claude) | grep "not found"
214```
215
216Run a quick sanity check that the binary can execute:
217
218```bash theme={null}
219claude --version
220```
221
222## Common installation issues
223
224These are the most frequently encountered installation problems and their solutions.
225
226### Install script returns HTML instead of a shell script
227
228When running the install command, you may see one of these errors:
229
230```text theme={null}
231bash: line 1: syntax error near unexpected token `<'
232bash: line 1: `<!DOCTYPE html>'
233```
234
235On PowerShell, the same problem appears as:
236
237```text theme={null}
238Invoke-Expression: Missing argument in parameter list.
239```
240
241This 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).
242
243Otherwise, this can happen due to network issues, regional routing, or a temporary service disruption.
244
245**Solutions:**
246
2471. **Use an alternative install method**:
248
249 On macOS or Linux, install via Homebrew:
250
251 ```bash theme={null}
252 brew install --cask claude-code
253 ```
254
255 On Windows, install via WinGet:
256
257 ```powershell theme={null}
258 winget install Anthropic.ClaudeCode
259 ```
260
2612. **Retry after a few minutes**: the issue is often temporary. Wait and try the original command again.
262
263### `command not found: claude` after installation
264
265The install finished but `claude` doesn't work. The exact error varies by platform:
266
267| Platform | Error message |
268| :---------- | :--------------------------------------------------------------------- |
269| macOS | `zsh: command not found: claude` |
270| Linux | `bash: claude: command not found` |
271| Windows CMD | `'claude' is not recognized as an internal or external command` |
272| PowerShell | `claude : The term 'claude' is not recognized as the name of a cmdlet` |
273
274This 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.
275
276### `curl: (56) Failure writing output to destination`
277
278The `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.
279
280**Solutions:**
281
2821. **Check network stability**: Claude Code binaries are hosted at `downloads.claude.ai`. Test that you can reach it:
283 ```bash theme={null}
284 curl -fsSL https://downloads.claude.ai -o /dev/null
285 ```
286 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.
287
2882. **Try an alternative install method**:
289
290 On macOS or Linux:
291
292 ```bash theme={null}
293 brew install --cask claude-code
294 ```
295
296 On Windows:
297
298 ```powershell theme={null}
299 winget install Anthropic.ClaudeCode
300 ```
301
302### TLS or SSL connection errors
303
304Errors 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.
305
306**Solutions:**
307
3081. **Update your system CA certificates**:
309
310 On Ubuntu/Debian:
311
312 ```bash theme={null}
313 sudo apt-get update && sudo apt-get install ca-certificates
314 ```
315
316 On macOS via Homebrew:
317
318 ```bash theme={null}
319 brew install ca-certificates
320 ```
321
3222. **On Windows, enable TLS 1.2** in PowerShell before running the installer:
323 ```powershell theme={null}
324 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
325 irm https://claude.ai/install.ps1 | iex
326 ```
327
3283. **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:
329 ```bash theme={null}
330 export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
331 ```
332 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.
333
3344. **On Windows, bypass certificate revocation checks** if you see `CRYPT_E_NO_REVOCATION_CHECK (0x80092012)` or `CRYPT_E_REVOCATION_OFFLINE (0x80092013)`. These mean curl reached the server but your network blocks the certificate revocation lookup, which is common behind corporate firewalls. Add `--ssl-revoke-best-effort` to the install command:
335 ```bat theme={null}
336 curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
337 ```
338 Alternatively, install with `winget install Anthropic.ClaudeCode`, which avoids curl entirely.
339
340### `Failed to fetch version from downloads.claude.ai`
341
342The installer couldn't reach the download server. This typically means `downloads.claude.ai` is blocked on your network.
343
344**Solutions:**
345
3461. **Test connectivity directly**:
347 ```bash theme={null}
348 curl -sI https://downloads.claude.ai
349 ```
350
3512. **If behind a proxy**, set `HTTPS_PROXY` so the installer can route through it. See [proxy configuration](/en/network-config#proxy-configuration) for details.
352 ```bash theme={null}
353 export HTTPS_PROXY=http://proxy.example.com:8080
354 curl -fsSL https://claude.ai/install.sh | bash
355 ```
356
3573. **If on a restricted network**, try a different network or VPN, or use an alternative install method:
358
359 On macOS or Linux:
360
361 ```bash theme={null}
362 brew install --cask claude-code
363 ```
364
365 On Windows:
366
367 ```powershell theme={null}
368 winget install Anthropic.ClaudeCode
369 ```
370
371### Windows: wrong install command
372
373If you see `'irm' is not recognized`, `The token '&&' is not valid`, or `'bash' is not recognized as the name of a cmdlet`, you copied the install command for a different shell or operating system.
374
375* **`irm` not recognized**: you're in CMD, not PowerShell. You have two options:
376
377 Open PowerShell by searching for "PowerShell" in the Start menu, then run the original install command:
378
379 ```powershell theme={null}
380 irm https://claude.ai/install.ps1 | iex
381 ```
382
383 Or stay in CMD and use the CMD installer instead:
384
385 ```batch theme={null}
386 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
387 ```
388
389* **`&&` not valid**: you're in PowerShell but ran the CMD installer command. Use the PowerShell installer:
390 ```powershell theme={null}
391 irm https://claude.ai/install.ps1 | iex
392 ```
393
394* **`bash` not recognized**: you ran the macOS/Linux installer on Windows. Use the PowerShell installer instead:
395 ```powershell theme={null}
396 irm https://claude.ai/install.ps1 | iex
397 ```
398
399### Install killed on low-memory Linux servers
400
401If you see `Killed` during installation on a VPS or cloud instance:
402
403```text theme={null}
404Setting up Claude Code...
405Installing Claude Code native build latest...
406bash: line 142: 34803 Killed "$binary_path" install ${TARGET:+"$TARGET"}
407```
408
409The Linux OOM killer terminated the process because the system ran out of memory. Claude Code requires at least 4 GB of available RAM.
410
411**Solutions:**
412
4131. **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.
414
415 Create a 2 GB swap file and enable it:
416
417 ```bash theme={null}
418 sudo fallocate -l 2G /swapfile
419 sudo chmod 600 /swapfile
420 sudo mkswap /swapfile
421 sudo swapon /swapfile
422 ```
423
424 Then retry the installation:
425
426 ```bash theme={null}
427 curl -fsSL https://claude.ai/install.sh | bash
428 ```
429
4302. **Close other processes** to free memory before installing.
431
4323. **Use a larger instance** if possible. Claude Code requires at least 4 GB of RAM.
433
434### Install hangs in Docker
435
436When installing Claude Code in a Docker container, installing as root into `/` can cause hangs.
437
438**Solutions:**
439
4401. **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:
441 ```dockerfile theme={null}
442 WORKDIR /tmp
443 RUN curl -fsSL https://claude.ai/install.sh | bash
444 ```
445
4462. **Increase Docker memory limits** if using Docker Desktop:
447 ```bash theme={null}
448 docker build --memory=4g .
449 ```
450
451### Windows: Claude Desktop overrides `claude` CLI command
452
453If 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.
454
455Update Claude Desktop to the latest version to fix this issue.
456
457### Windows: "Claude Code on Windows requires either Git for Windows (for bash) or PowerShell"
458
459Claude Code on native Windows needs at least one shell: either [Git for Windows](https://git-scm.com/downloads/win) for Bash, or PowerShell. When neither is found, this error appears at startup. If only PowerShell is found, Claude Code uses the PowerShell tool instead of Bash.
460
461**If neither is installed**, install one:
462
463* Git for Windows: download from [git-scm.com/downloads/win](https://git-scm.com/downloads/win). During setup, select "Add to PATH." Restart your terminal after installing.
464* PowerShell 7: download from [aka.ms/powershell](https://aka.ms/powershell).
465
466**If Git is already installed** but Claude Code can't find it, set the path in your [settings.json file](/en/settings):
467
468```json theme={null}
469{
470 "env": {
471 "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
472 }
473}
474```
475
476If 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.
477
478### Windows: Claude Code does not support 32-bit Windows
479
480Windows includes two PowerShell entries in the Start menu: `Windows PowerShell` and `Windows PowerShell (x86)`. The x86 entry runs as a 32-bit process and triggers this error even on a 64-bit machine. To check which case you're in, run this in the same window that produced the error:
481
482```powershell theme={null}
483[Environment]::Is64BitOperatingSystem
484```
485
486If this prints `True`, your operating system is fine. Close the window, open `Windows PowerShell` without the x86 suffix, and run the install command again.
487
488If this prints `False`, you are on a 32-bit edition of Windows. Claude Code requires a 64-bit operating system. See the [system requirements](/en/setup#system-requirements).
489
490### Linux: wrong binary variant installed (musl/glibc mismatch)
491
492If 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.
493
494```text theme={null}
495Error loading shared library libstdc++.so.6: No such file or directory
496```
497
498This can happen on glibc-based systems that have musl cross-compilation packages installed, causing the installer to misdetect the system as musl.
499
500**Solutions:**
501
5021. **Check which libc your system uses**:
503 ```bash theme={null}
504 ldd /bin/ls | head -1
505 ```
506 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.
507
5082. **If you're on glibc but got the musl binary**, remove the installation and reinstall. You can also manually download the correct binary using the manifest at `https://downloads.claude.ai/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*`.
509
5103. **If you're actually on musl** (Alpine Linux), install the required packages:
511 ```bash theme={null}
512 apk add libgcc libstdc++ ripgrep
513 ```
514
515### `Illegal instruction` on Linux
516
517If 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.
518
519```text theme={null}
520bash: line 142: 2238232 Illegal instruction "$binary_path" install ${TARGET:+"$TARGET"}
521```
522
523**Verify your architecture**:
524
525```bash theme={null}
526uname -m
527```
528
529`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. Alternative install methods download the same architecture-specific binary and won't resolve this error.
530
531### `dyld: cannot load` on macOS
532
533If you see `dyld: cannot load`, `dyld: Symbol not found`, or `Abort trap: 6` during installation, the binary is incompatible with your macOS version or hardware.
534
535```text theme={null}
536dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
537Abort trap: 6
538```
539
540A `Symbol not found` error that references `libicucore` also indicates your macOS version is older than the binary supports:
541
542```text theme={null}
543dyld: Symbol not found: _ubrk_clone
544 Referenced from: claude-darwin-x64 (which was built for Mac OS X 13.0)
545 Expected in: /usr/lib/libicucore.A.dylib
546```
547
548**Solutions:**
549
5501. **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.
551
5522. **Update macOS** if you're on an older version. The binary uses load commands and system libraries that older macOS versions don't support. Alternative install methods like Homebrew download the same binary and won't resolve this error.
553
554### Windows installation issues: errors in WSL
555
556You might encounter the following issues in WSL:
557
558**OS/platform detection issues**: if you receive an error during installation, WSL may be using Windows `npm`. Try:
559
560* Run `npm config set os linux` before installation
561* Install with `npm install -g @anthropic-ai/claude-code --force --no-os-check`. Do not use `sudo`.
562
563**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).
564
565**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.
566
567You can identify this issue by:
568
569* Running `which npm` and `which node` - if they point to Windows paths (starting with `/mnt/c/`), Windows versions are being used
570* Experiencing broken functionality after switching Node versions with nvm in WSL
571
572To resolve this issue, fix your Linux PATH to ensure the Linux node/npm versions take priority:
573
574**Primary solution: Ensure nvm is properly loaded in your shell**
575
576The most common cause is that nvm isn't loaded in non-interactive shells. Add the following to your shell configuration file (`~/.bashrc`, `~/.zshrc`, etc.):
577
578```bash theme={null}
579# Load nvm if it exists
580export NVM_DIR="$HOME/.nvm"
581[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
582[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
583```
584
585Or run directly in your current session:
586
587```bash theme={null}
588source ~/.nvm/nvm.sh
589```
590
591**Alternative: Adjust PATH order**
592
593If nvm is properly loaded but Windows paths still take priority, you can explicitly prepend your Linux paths to PATH in your shell configuration:
594
595```bash theme={null}
596export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"
597```
598
599<Warning>
600 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.
601</Warning>
602
603### WSL2 sandbox setup
604
605[Sandboxing](/en/sandboxing) is supported on WSL2 but requires installing additional packages. If you see an error about missing `bubblewrap` or `socat` when running `/sandbox`, install the dependencies:
606
607<Tabs>
608 <Tab title="Ubuntu/Debian">
609 ```bash theme={null}
610 sudo apt-get install bubblewrap socat
611 ```
612 </Tab>
613
614 <Tab title="Fedora">
615 ```bash theme={null}
616 sudo dnf install bubblewrap socat
617 ```
618 </Tab>
619</Tabs>
620
621WSL1 does not support sandboxing. If you see "Sandboxing requires WSL2", you need to upgrade to WSL2 or run Claude Code without sandboxing.
622
623Sandboxed commands cannot launch Windows binaries such as `cmd.exe`, `powershell.exe`, or executables under `/mnt/c/`. WSL hands these off to the Windows host over a Unix socket, which the sandbox blocks. If a command needs to invoke a Windows binary, add it to [`excludedCommands`](/en/settings#sandbox-settings) so it runs outside the sandbox.
624
625### Permission errors during installation
626
627If the native installer fails with permission errors, the target directory may not be writable. See [Check directory permissions](#check-directory-permissions).
628
629If you previously installed with npm and are hitting npm-specific permission errors, switch to the native installer:
630
631```bash theme={null}
632curl -fsSL https://claude.ai/install.sh | bash
633```
634
635### Native binary not found after npm install
636
637The `@anthropic-ai/claude-code` npm package pulls in the native binary through a per-platform optional dependency such as `@anthropic-ai/claude-code-darwin-arm64`. If running `claude` after install prints `Could not find native binary package "@anthropic-ai/claude-code-<platform>"`, check the following causes:
638
639* **Optional dependencies are disabled.** Remove `--omit=optional` from your npm install command, `--no-optional` from pnpm, or `--ignore-optional` from yarn, and check that `.npmrc` does not set `optional=false`. Then reinstall. The native binary is delivered only as an optional dependency, so there is no JavaScript fallback if it is skipped.
640* **Unsupported platform.** Prebuilt binaries are published for `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `linux-x64-musl`, `linux-arm64-musl`, `win32-x64`, and `win32-arm64`. Claude Code does not ship a binary for other platforms; see the [system requirements](/en/setup#system-requirements).
641* **Corporate npm mirror is missing the platform packages.** Ensure your registry mirrors all eight `@anthropic-ai/claude-code-*` platform packages in addition to the meta package.
642
643Installing with `--ignore-scripts` does not trigger this error. The postinstall step that links the binary into place is skipped, so Claude Code falls back to a wrapper that locates and spawns the platform binary on each launch. This works but starts more slowly; reinstall with scripts enabled for direct execution.
644
645## Permissions and authentication
646
647These sections address login failures, token issues, and permission prompt behavior.
648
649### Repeated permission prompts
650
651If you find yourself repeatedly approving the same commands, you can allow specific tools
652to run without approval using the `/permissions` command. See [Permissions docs](/en/permissions#manage-permissions).
653
654### Authentication issues
655
656If you're experiencing authentication problems:
657
6581. Run `/logout` to sign out completely
6592. Close Claude Code
6603. Restart with `claude` and complete the authentication process again
661
662If 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.
663
664### OAuth error: Invalid code
665
666If you see `OAuth error: Invalid code. Please make sure the full code was copied`, the login code expired or was truncated during copy-paste.
667
668**Solutions:**
669
670* Press Enter to retry and complete the login quickly after the browser opens
671* Type `c` to copy the full URL if the browser doesn't open automatically
672* 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.
673
674### 403 Forbidden after login
675
676If you see `API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}` after logging in:
677
678* **Claude Pro/Max users**: verify your subscription is active at [claude.ai/settings](https://claude.ai/settings)
679* **Console users**: confirm your account has the "Claude Code" or "Developer" role assigned by your admin
680* **Behind a proxy**: corporate proxies can interfere with API requests. See [network configuration](/en/network-config) for proxy setup.
681
682### Model not found or not accessible
683
684If you see `There's an issue with the selected model (...). It may not exist or you may not have access to it`, the API rejected the configured model name.
685
686Common causes:
687
688* A typo in the model name passed to `--model`
689* A stale or deprecated model ID saved in your settings
690* An API key without access to that model on your current usage tier
691
692Check where the model is set, in [priority order](/en/model-config#setting-your-model):
693
694* The `--model` flag
695* The `ANTHROPIC_MODEL` environment variable
696* The `model` field in `.claude/settings.local.json`
697* The `model` field in your project's `.claude/settings.json`
698* The `model` field in `~/.claude/settings.json`
699
700To clear a stale value, remove the `model` field from your settings or unset `ANTHROPIC_MODEL`, and Claude Code will fall back to the default model for your account.
701
702To browse models available to your account, start `claude` interactively and run `/model` to open the picker. For Vertex AI deployments, see [the Vertex AI troubleshooting section](/en/google-vertex-ai#troubleshooting).
703
704### This organization has been disabled with an active subscription
705
706If you see `API Error: 400 ... "This organization has been disabled"` despite having an active Claude subscription, an `ANTHROPIC_API_KEY` environment variable is overriding your subscription. This commonly happens when an old API key from a previous employer or project is still set in your shell profile.
707
708When `ANTHROPIC_API_KEY` is present and you have approved it, Claude Code uses that key instead of your subscription's OAuth credentials. In non-interactive mode (`-p`), the key is always used when present. See [authentication precedence](/en/authentication#authentication-precedence) for the full resolution order.
709
710To use your subscription instead, unset the environment variable and remove it from your shell profile:
711
712```bash theme={null}
713unset ANTHROPIC_API_KEY
714claude
715```
716
717Check `~/.zshrc`, `~/.bashrc`, or `~/.profile` for `export ANTHROPIC_API_KEY=...` lines and remove them to make the change permanent. Run `/status` inside Claude Code to confirm which authentication method is active.
718
719### OAuth login fails in WSL2
720
721Browser-based login in WSL2 may fail if WSL can't open your Windows browser. Set the `BROWSER` environment variable:
722
723```bash theme={null}
724export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
725claude
726```
727
728Or copy the URL manually: when the login prompt appears, press `c` to copy the OAuth URL, then paste it into your Windows browser.
729
730### Not logged in or token expired
731
732If Claude Code prompts you to log in again after a session, your OAuth token may have expired.
733
734Run `/login` to re-authenticate. If this happens frequently, check that your system clock is accurate, as token validation depends on correct timestamps.
735
736On macOS, login can also fail when the Keychain is locked or its password is out of sync with your account password, which prevents Claude Code from saving credentials. Run `claude doctor` to check Keychain access. To unlock the Keychain manually, run `security unlock-keychain ~/Library/Keychains/login.keychain-db`. If unlocking doesn't help, open Keychain Access, select the `login` keychain, and choose Edit > Change Password for Keychain "login" to resync it with your account password.
737
738## Configuration file locations
739
740Claude Code stores configuration in several locations:
741
742| File | Purpose |
743| :---------------------------- | :----------------------------------------------------------------------------------------------------- |
744| `~/.claude/settings.json` | User settings (permissions, hooks, model overrides) |
745| `.claude/settings.json` | Project settings (checked into source control) |
746| `.claude/settings.local.json` | Local project settings (not committed) |
747| `~/.claude.json` | Global state (theme, OAuth, MCP servers) |
748| `.mcp.json` | Project MCP servers (checked into source control) |
749| `managed-mcp.json` | [Managed MCP servers](/en/mcp#managed-mcp-configuration) |
750| Managed settings | [Managed settings](/en/settings#settings-files) (server-managed, MDM/OS-level policies, or file-based) |
751
752On Windows, `~` refers to your user home directory, such as `C:\Users\YourName`.
753
754For details on configuring these files, see [Settings](/en/settings) and [MCP](/en/mcp).
755
756### Resetting configuration
757
758To reset Claude Code to default settings, you can remove the configuration files:
759
760```bash theme={null}
761# Reset all user settings and state
762rm ~/.claude.json
763rm -rf ~/.claude/
764
765# Reset project-specific settings
766rm -rf .claude/
767rm .mcp.json
768```
769
770<Warning>
771 This will remove all your settings, MCP server configurations, and session history.
772</Warning>
773 23
774## Performance and stability24## Performance and stability
775 25
7832. Close and restart Claude Code between major tasks332. Close and restart Claude Code between major tasks
7843. Consider adding large build directories to your `.gitignore` file343. Consider adding large build directories to your `.gitignore` file
785 35
786If memory usage stays high after these steps, run `/heapdump` to write a JavaScript heap snapshot and a memory breakdown to `~/Desktop`. The breakdown shows resident set size, JS heap, array buffers, and unaccounted native memory, which helps identify whether the growth is in JavaScript objects or in native code. Open the `.heapsnapshot` file in Chrome DevTools under Memory → Load to inspect retainers. Attach both files when reporting a memory issue on [GitHub](https://github.com/anthropics/claude-code/issues).36If memory usage stays high after these steps, run `/heapdump` to write a JavaScript heap snapshot and a memory breakdown to `~/Desktop`. On Linux without a Desktop folder, the files are written to your home directory.
37
38The breakdown shows resident set size, JS heap, array buffers, and unaccounted native memory, which helps identify whether the growth is in JavaScript objects or in native code. To inspect retainers, open the `.heapsnapshot` file in Chrome DevTools under Memory → Load. Attach both files when reporting a memory issue on [GitHub](https://github.com/anthropics/claude-code/issues).
787 39
788### Auto-compaction stops with a thrashing error40### Auto-compaction stops with a thrashing error
789 41
8031. Press Ctrl+C to attempt to cancel the current operation551. Press Ctrl+C to attempt to cancel the current operation
8042. If unresponsive, you may need to close the terminal and restart562. If unresponsive, you may need to close the terminal and restart
805 57
58Restarting doesn't lose your conversation. Run `claude --resume` in the same directory to pick the session back up.
59
806### Search and discovery issues60### Search and discovery issues
807 61
808If Search tool, `@file` mentions, custom agents, and custom skills aren't working, install system `ripgrep`:62If the Search tool, `@file` mentions, custom agents, or custom skills aren't finding files, the bundled `ripgrep` binary may not run on your system. Install your platform's `ripgrep` package and tell Claude Code to use it instead:
809 63
810```bash theme={null}64<Tabs>
811# macOS (Homebrew) 65 <Tab title="macOS">
812brew install ripgrep66 ```bash theme={null}
67 brew install ripgrep
68 ```
69 </Tab>
813 70
814# Windows (winget)71 <Tab title="Ubuntu/Debian">
815winget install BurntSushi.ripgrep.MSVC72 ```bash theme={null}
73 sudo apt install ripgrep
74 ```
75 </Tab>
816 76
817# Ubuntu/Debian77 <Tab title="Alpine">
818sudo apt install ripgrep78 ```bash theme={null}
79 apk add ripgrep
80 ```
81 </Tab>
819 82
820# Alpine Linux83 <Tab title="Arch">
821apk add ripgrep84 ```bash theme={null}
85 pacman -S ripgrep
86 ```
87 </Tab>
822 88
823# Arch Linux89 <Tab title="Windows">
824pacman -S ripgrep90 ```powershell theme={null}
825```91 winget install BurntSushi.ripgrep.MSVC
92 ```
93 </Tab>
94</Tabs>
826 95
827Then set `USE_BUILTIN_RIPGREP=0` in your [environment](/en/env-vars).96Then set `USE_BUILTIN_RIPGREP=0` in your [environment](/en/env-vars).
828 97
842 111
8433. **Use native Windows instead**: consider running Claude Code natively on Windows instead of through WSL, for better file system performance.1123. **Use native Windows instead**: consider running Claude Code natively on Windows instead of through WSL, for better file system performance.
844 113
845## IDE integration issues
846
847If Claude Code does not connect to your IDE or behaves unexpectedly within an IDE terminal, try the solutions below.
848
849### JetBrains IDE not detected on WSL2
850
851If 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.
852
853#### WSL2 networking modes
854
855WSL2 uses NAT networking by default, which can prevent IDE detection. You have two options:
856
857**Option 1: Configure Windows Firewall** (recommended)
858
8591. Find your WSL2 IP address:
860 ```bash theme={null}
861 wsl hostname -I
862 # Example output: 172.21.123.45
863 ```
864
8652. Open PowerShell as Administrator and create a firewall rule:
866 ```powershell theme={null}
867 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
868 ```
869 Adjust the IP range based on your WSL2 subnet from step 1.
870
8713. Restart both your IDE and Claude Code
872
873**Option 2: Switch to mirrored networking**
874
875Add to `.wslconfig` in your Windows user directory:
876
877```ini theme={null}
878[wsl2]
879networkingMode=mirrored
880```
881
882Then restart WSL with `wsl --shutdown` from PowerShell.
883
884<Note>
885 These networking issues only affect WSL2. WSL1 uses the host's network directly and doesn't require these configurations.
886</Note>
887
888For additional JetBrains configuration tips, see the [JetBrains IDE guide](/en/jetbrains#plugin-settings).
889
890### Report Windows IDE integration issues
891
892If you're experiencing IDE integration problems on Windows, [create an issue](https://github.com/anthropics/claude-code/issues) with the following information:
893
894* Environment type: native Windows (Git Bash) or WSL1/WSL2
895* WSL networking mode, if applicable: NAT or mirrored
896* IDE name and version
897* Claude Code extension/plugin version
898* Shell type: Bash, Zsh, PowerShell, etc.
899
900### Escape key not working in JetBrains IDE terminals
901
902If 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.
903
904To fix this issue:
905
9061. Go to Settings → Tools → Terminal
9072. Either:
908 * Uncheck "Move focus to the editor with Escape", or
909 * Click "Configure terminal keybindings" and delete the "Switch focus to Editor" shortcut
9103. Apply the changes
911
912This allows the `Esc` key to properly interrupt Claude Code operations.
913
914## Markdown formatting issues
915
916Claude Code sometimes generates markdown files with missing language tags on code fences, which can affect syntax highlighting and readability in GitHub, editors, and documentation tools.
917
918### Missing language tags in code blocks
919
920If you notice code blocks like this in generated markdown:
921
922````markdown theme={null}
923```
924function example() {
925 return "hello";
926}
927```
928````
929
930Instead of properly tagged blocks like:
931
932````markdown theme={null}
933```javascript
934function example() {
935 return "hello";
936}
937```
938````
939
940**Solutions:**
941
9421. **Ask Claude to add language tags**: request "Add appropriate language tags to all code blocks in this markdown file."
943
9442. **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.
945
9463. **Manual verification**: after generating markdown files, review them for proper code block formatting and request corrections if needed.
947
948### Inconsistent spacing and formatting
949
950If generated markdown has excessive blank lines or inconsistent spacing:
951
952**Solutions:**
953
9541. **Request formatting corrections**: ask Claude to "Fix spacing and formatting issues in this markdown file."
955
9562. **Use formatting tools**: set up hooks to run markdown formatters like `prettier` or custom formatting scripts on generated markdown files.
957
9583. **Specify formatting preferences**: include formatting requirements in your prompts or project [memory](/en/memory) files.
959
960### Reduce markdown formatting issues
961
962To minimize formatting issues:
963
964* **Be explicit in requests**: ask for "properly formatted markdown with language-tagged code blocks"
965* **Use project conventions**: document your preferred markdown style in [`CLAUDE.md`](/en/memory)
966* **Set up validation hooks**: use post-processing hooks to automatically verify and fix common formatting issues
967
968## Get more help114## Get more help
969 115
970If you're experiencing issues not covered here:116If you're experiencing issues not covered here:
971 117
9721. See the [Error reference](/en/errors) for `API Error: 5xx`, `529 Overloaded`, `429`, and request validation errors that appear during a session1181. Run `/doctor` to check installation health, settings validity, MCP configuration, and context usage in one pass
9732. Use the `/feedback` command within Claude Code to report problems directly to Anthropic1192. Use the `/feedback` command within Claude Code to report problems directly to Anthropic
9743. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues1203. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues
9754. Run `/doctor` to diagnose issues. It checks:1214. Ask Claude directly about its capabilities and features. Claude has built-in access to its documentation.
976 * Installation type, version, and search functionality
977 * Auto-update status and available versions
978 * Invalid settings files (malformed JSON, incorrect types)
979 * MCP server configuration errors, including the same server name defined in multiple scopes with different endpoints
980 * Keybinding configuration problems
981 * Context usage warnings (large CLAUDE.md files, high MCP token usage, unreachable permission rules)
982 * Plugin and agent loading errors
9835. Ask Claude directly about its capabilities and features - Claude has built-in access to its documentation
