Skip to main content
If installation fails or you can’t sign in, find your error below. For runtime issues after Claude Code is working, see Troubleshooting. For configuration problems such as settings not applying or hooks not firing, see Debug your configuration.

​
Find your error

Match the error message or symptom you’re seeing to a fix: If your issue isn’t listed, work through the diagnostic checks below to narrow down the cause.
If you’d rather skip the terminal entirely, the Claude Code Desktop app lets you install and use Claude Code through a graphical interface. Download it for macOS or Windows and start coding without any command-line setup. On Linux, install the app with apt by following the Linux install instructions.

​
Run diagnostic checks

​
Check network connectivity

The installer downloads from downloads.claude.ai. Verify you can reach it:
You reached the server if the first line shows a 200 status. You see HTTP/2 200 on macOS and Linux, and HTTP/1.1 200 OK from the curl.exe included with Windows. Other results point to the cause:
  • 403: usually a proxy or network filter blocking the host, or Claude Code is not available in your region
  • 5xx: usually a temporary service issue; wait a few minutes and retry
If you see no output, Could not resolve host, or a connection timeout, your network is blocking the connection. Common causes:
  • Corporate firewalls or proxies blocking downloads.claude.ai
  • Regional network restrictions: try a VPN or alternative network
  • TLS/SSL issues: update your system’s CA certificates, or check if HTTPS_PROXY is configured
If 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. This example sets both proxy variables, then runs the installer through your proxy:

​
Verify your PATH

If 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. The 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.
The VS Code extension 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 to use claude from a terminal, then continue below.
First 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.
Check that the installer put the program in place:
  • 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. If you installed it another way, see Check for conflicting installations.
  • A listing for the file: the program is there. Check your PATH next.
List your PATH entries and filter for the install folder:
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. 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.For Zsh, the default on macOS:
For Bash on Linux, where it’s the default on most distributions:
For Bash on macOS, add the line to ~/.bash_profile instead. Terminal on macOS starts Bash as a login shell, which ignores ~/.bashrc and reads only the first of ~/.bash_profile, ~/.bash_login, or ~/.profile that exists. If you already have a ~/.bash_login or ~/.profile and no ~/.bash_profile, put the line in that file rather than creating ~/.bash_profile:
Alternatively, close and reopen your terminal.If the echo command prints permission denied, see permission denied when adding to your PATH.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.Verify the fix worked:
If claude is still not found, check these causes:
  • 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.
  • 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.
  • The line went to another shell’s file: run echo $0 to see your shell, then run the two PATH commands for that shell.

​
Check for conflicting installations

Multiple Claude Code installations can cause version mismatches or unexpected behavior. Check what’s installed:
List all claude binaries found in your PATH:
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.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:
A native install shows a symlink into ~/.local/share/claude/versions/. A script or a symlink you created yourself at this path is a custom launcher, which auto-update leaves in place.If either ls command prints No such file or directory, that’s not an error. It means nothing is installed at that location, so move on to the next check.
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. If ~/.local/bin/claude exists but which -a claude didn’t list it, the folder isn’t in your PATH: see Verify your PATH.
If you find multiple installations, keep only one. The native install at ~/.local/bin/claude on macOS/Linux or %USERPROFILE%\.local\bin\claude.exe on Windows is recommended. Remove the extras: Uninstall an npm global install:
Remove the legacy local npm install:
Remove a Homebrew install on macOS. If you installed the claude-code@latest cask, substitute that name:
Remove a WinGet install on Windows:

​
Check directory permissions

An install that fails on permissions names the path it couldn’t create or write. On Windows the install writes under %USERPROFILE%, which is writable by your user by default, so this section rarely applies there. On macOS and Linux the install writes to these locations:
  • ~/.claude/downloads/: where the install command puts the downloaded binary
  • ~/.local/bin/: the claude launcher
  • ~/.local/share/claude/: each version it downloads
  • ~/.local/state/claude/: its lock files
  • ~/.cache/claude/: staged downloads
  • ~/.claude.json: your global config file, where the installer records the install method
If you set XDG_DATA_HOME, XDG_STATE_HOME, or XDG_CACHE_HOME, the install uses those in place of ~/.local/share, ~/.local/state, and ~/.cache. If you set CLAUDE_CONFIG_DIR, the global config file lives under that directory instead of your home directory. Check whether the directories are writable:
If either directory isn’t writable, create the install directory and set your user as the owner:

​
Verify the binary works

If claude --version prints a version but claude crashes or hangs on startup, run these checks to narrow down the cause. If claude --version says command not found, go to Verify your PATH first; the commands below assume claude is on your PATH. Confirm the binary exists and is executable:
On 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.
Confirm the binary can execute:

​
Common installation issues

These are the most frequently encountered installation problems and their solutions.

​
Install script returns HTML instead of a shell script

The install command fails with one of these errors when what it downloaded isn’t the install script. Bash or Zsh: the error quotes the first line of the returned page.
PowerShell, parse errors: the errors point into the returned page, with iex trying to run HTML and CSS as PowerShell.
The 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. PowerShell, System.Xml.XmlDocument: the error names this type instead of quoting the page.
When 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. CMD: you see this error, followed by the HTML of the returned page.
The first line appears in your system language, so look for the HTML that follows it. A 403 with no page: depending on how the request was routed, curl reports a 403 status with no HTML body.
These 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. A 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 before trying the alternative installers below, since those reach the same hosts. Otherwise, this can happen due to network issues, regional routing, or a temporary service disruption. Solutions:
  1. Retry after a few minutes: the issue is often temporary. Wait and try the original command again.
  2. Use an alternative install method: unlike a native install, a Homebrew or WinGet install doesn’t update itself by default. On macOS, install via Homebrew:
    On Windows, install via WinGet:
    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.

​
command not found: claude after installation

The install finished but claude doesn’t work. The exact error varies by platform: On Windows, if the error started right after Claude Code updated, see restore claude.exe from its backup. Otherwise, see Verify your PATH for the fix on each platform.

​
permission denied when adding to your PATH

If 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:
The third field of the output is the owner.
  • The owner is another user, such as root: take ownership with sudo chown $(whoami) ~/.zshrc, which requires administrator rights.
  • The owner is you: the file is read-only. Make it writable with chmod u+w ~/.zshrc.
Then run the two PATH commands for your shell in Verify your PATH again.

​
curl: (56) Failure writing output to destination

The 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. Test that you can reach downloads.claude.ai with the check in Check network connectivity. If you reached the server, the original failure was likely intermittent; retry the install command. You can also try an alternative install method.

​
Homebrew cask unavailable or outdated

Homebrew reports Error: Cask 'claude-code' is unavailable: No Cask with this name exists when your local copy of the Homebrew cask index predates the cask’s publication. Refresh the index and retry:
If 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 for the difference between the two casks.

​
Cask 'claude-code@latest' is not installed

Homebrew 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:
Upgrade the cask it prints. If it prints nothing, neither cask is installed.

​
TLS or SSL connection errors

Errors such as these mean the TLS handshake failed:
  • curl: (35) TLS connect error
  • schannel: next InitializeSecurityContext failed
  • PowerShell’s Could not create SSL/TLS secure channel
  • PowerShell’s Could not establish trust relationship for the SSL/TLS secure channel
For CRYPT_E_NO_REVOCATION_CHECK or CRYPT_E_REVOCATION_OFFLINE, go to step 4. Solutions:
  1. Update your system CA certificates: On Ubuntu/Debian:
    On macOS, the system curl uses the Keychain trust store; updating macOS itself updates the root certificates.
  2. In Windows PowerShell 5.1, enable TLS 1.2:
    Then run the installer in the same window:
  3. Check for proxy or firewall interference: corporate proxies that perform TLS inspection can cause these errors, including unable to get local issuer certificate and SELF_SIGNED_CERT_IN_CHAIN. For the install step, make the install download trust your corporate proxy’s CA:
    For Claude Code itself once installed, set NODE_EXTRA_CA_CERTS so API requests trust the same bundle:
    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.
  4. On Windows, work around blocked revocation checks. The errors CRYPT_E_NO_REVOCATION_CHECK (0x80092012) and CRYPT_E_REVOCATION_OFFLINE (0x80092013) mean curl reached the server but your network blocks the certificate revocation lookup, which is common behind corporate firewalls. If the failing command is the curl that downloads install.cmd, rerun it from a Command Prompt with --ssl-revoke-best-effort added:
    When the script’s own downloads hit the same errors, it retries them with best-effort revocation checking automatically, so the flag is only needed on the command you run yourself. Best-effort checking tolerates an unreachable revocation server but still rejects a certificate that is known to be revoked, matching how browsers handle revocation. You can also avoid curl’s revocation check entirely by running the PowerShell installer from PowerShell, which downloads through .NET and doesn’t fail when the revocation server is unreachable:
    You can also install with winget install Anthropic.ClaudeCode, which avoids curl entirely.

​
Failed to fetch version from downloads.claude.ai

The installer couldn’t reach the download server. This typically means downloads.claude.ai is blocked on your network. See Check network connectivity.

​
The connection dropped while downloading the update

The 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.
The 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. A 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. A proxy or gateway can close a long transfer before it finishes, and the Claude Code binary is a large download. What to do:
  • 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.
  • If your network requires a proxy, set HTTPS_PROXY before running the installer or claude update. See Check network connectivity.
  • 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.
  • Run claude doctor from your shell for installation diagnostics

​
Wrong install command on Windows

If 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.
  • irm not recognized: you’re in CMD, not PowerShell. You have two options: Open PowerShell by searching for “PowerShell” in the Start menu, then run the original install command:
    Or stay in CMD and use the CMD installer instead:
  • && not a valid statement separator: you’re in PowerShell but ran the CMD installer command. Use the PowerShell installer:
  • A parameter cannot be found that matches parameter name 'fsSL': you ran the macOS/Linux curl -fsSL ... | bash installer in Windows PowerShell, where curl is an alias for Invoke-WebRequest and rejects the -fsSL flags. Use the PowerShell installer instead:
  • bash not recognized: you ran the macOS/Linux installer on Windows. Use the PowerShell installer instead:
  • The command prints script text instead of installing: you ran the download half of the command without the part that executes it. irm https://claude.ai/install.ps1 on its own prints the downloaded script to the terminal. Pipe it to iex to run it:
    In CMD, curl -fsSL https://claude.ai/install.cmd without -o prints the batch script instead of saving it. Run the complete command:
Whichever installer you use, confirm it worked: open a new terminal and run claude --version, which prints a version number such as 2.1.211 (Claude Code).

​
running scripts is disabled on this system

Installing or running Claude Code through npm on Windows can fail with a SecurityError:
The same error names claude.ps1 when you run claude after an npm install. PowerShell’s execution policy is blocking the .ps1 launcher scripts that npm creates for its commands. The policy applies to script files, so it doesn’t affect the PowerShell installer irm https://claude.ai/install.ps1 | iex, which runs the downloaded text directly. Solutions:
  1. Allow locally created scripts for your user, then retry:
  2. Call the .cmd launcher instead: npm.cmd and claude.cmd do the same job, and the policy doesn’t cover them.
  3. Use the PowerShell installer instead of npm. It installs a binary rather than a .ps1 script.

​
The process cannot access the file during Windows install

If the PowerShell installer fails with Failed to download binary: The process cannot access the file ... because it is being used by another process, the installer couldn’t write to %USERPROFILE%\.claude\downloads. This usually means a previous install attempt is still running, or antivirus software is scanning a partially downloaded binary in that folder. Close any other PowerShell windows running the installer and wait for antivirus scans to release the file. Then delete the downloads folder and run the installer again:

​
claude.exe missing after an update on Windows

If your terminal reports 'claude' is not recognized right after Claude Code updated on Windows, check whether %USERPROFILE%\.local\bin still contains claude.exe. If that directory isn’t on your PATH at all, see Verify your PATH instead. To update on Windows, Claude Code renames the existing claude.exe aside to a backup and moves the new version into its place. If moving the new version into place fails and Claude Code can’t rename the backup back either, the directory keeps the backup but has no claude.exe. The backup is a file in the same directory whose name begins with claude.exe.old. followed by a numeric timestamp. Run the following in PowerShell to rename the newest backup back to claude.exe:
Then run claude --version to confirm the fix. A restored claude.exe prints a version number. If there’s no claude.exe.old.* file, or claude still fails after the rename, reinstall instead:
Before v2.1.281, Claude Code could delete the backup while claude.exe was still missing.

​
Install killed on low-memory Linux servers

A Killed message during install usually means the Linux out-of-memory (OOM) killer terminated the claude install step because the system ran out of free memory. This is common on small VPS and cloud instances. The install script reports the cause and exits with code 137. In this example, the line number and process ID vary by release and run:
Installing needs roughly 512 MB of free memory, and running Claude Code needs more. See the system requirements. Solutions:
  1. 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. Create a 2 GB swap file and enable it:
    Then retry the installation:
  2. Close other processes to free memory before installing.
  3. Use a larger instance if possible. Claude Code requires at least 4 GB of RAM.

​
Installation was killed before it could finish

The 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:
For 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. What to do:

​
Install hangs in Docker

When installing Claude Code in a Docker container, installing as root into / can cause hangs. Solutions:
  1. 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:
  2. Give Docker more memory if using Docker Desktop. Build containers share the memory allocated to the Docker Desktop virtual machine, so open Settings > Resources in Docker Desktop, raise the memory limit, and rerun the build.

​
Raw mode is not supported during install

When your organization’s server-managed settings include changes that need security approval, Claude Code versions before 2.1.246 try to show the approval dialog during claude install. The dialog needs a terminal on stdin. When the installer runs claude install from a pipe, as curl -fsSL https://claude.ai/install.sh | bash does, stdin is the pipe rather than a terminal, so the install fails with an error containing Raw mode is not supported. Claude Code v2.1.246 and later don’t show the dialog during claude install or claude update. The command runs with the settings you last approved, and Claude Code shows the dialog in your next interactive session. If your organization’s startup configuration waits for the settings fetch, such as when it sets forceRemoteSettingsRefresh, the dialog still appears during these commands, and an install run from a pipe still fails. In every other configuration, rerunning the installer gets past this error, because the script runs the latest release’s install command even when you ask it to install an older version. Rerun the command for your platform:
claude --version prints the version the rerun installed.

​
claude update or claude doctor hangs

claude update and claude doctor scan your shell configuration files for an outdated claude alias: ~/.zshrc, ~/.bashrc, and ~/.config/fish/config.fish, plus on macOS the first of ~/.bash_profile, ~/.bash_login, or ~/.profile that exists. If you set ZDOTDIR, the Zsh file is $ZDOTDIR/.zshrc instead. When one of those paths is a directory, Claude Code skips it and both commands complete normally. Before v2.1.214, a directory at one of those paths made both commands hang and left the System diagnostics section of /status blank. claude doctor hung with no output; claude update hung right after printing Checking for updates. If you hit the hang on an earlier version, find the directory. In this command’s output, a line starting with d marks that path as a directory. A No such file or directory line means nothing exists at that path and isn’t the cause:
Move the directory aside, or update to v2.1.214 or later. Since claude update hangs on the affected versions, update by rerunning the install script instead.

​
Claude Desktop overrides the claude command on Windows

If 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. Update Claude Desktop to the latest version to fix this issue.

​
Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

Git for Windows is optional. Claude Code uses the PowerShell tool when Git Bash is absent, so this error means neither shell was found. If PowerShell is missing from your PATH, its default location is C:\Windows\System32\WindowsPowerShell\v1.0\. Add that directory to your PATH, or install PowerShell 7, which provides pwsh. To install Git for Windows instead, download it from git-scm.com/downloads/win. During setup, select “Add to PATH.” Restart your terminal after installing. Installing it enables the Bash tool, useful when working with Bash-based scripts and tooling. If Git is already installed but Claude Code can’t find it, compare its location against the places Claude Code checks. When CLAUDE_CODE_GIT_BASH_PATH isn’t set, Claude Code looks for bash.exe in this order:
  1. The default install locations C:\Program Files\Git and C:\Program Files (x86)\Git.
  2. The git on your PATH, using the bin\bash.exe from that Git installation.
In step 2, Claude Code skips a git that sits in the folder you launched Claude Code from, or below it in a path that contains node_modules or a virtual-environment folder such as .venv or env, for example C:\dev\env\myproject\Git when you launched from C:\dev\env\myproject. This keeps Claude Code from running an executable that a project placed there. If your Git is in a location like that, point CLAUDE_CODE_GIT_BASH_PATH at it. To point Claude Code at a specific Git installation, find it by running where.exe git in PowerShell, then set the bin\bash.exe path from that installation as CLAUDE_CODE_GIT_BASH_PATH in your settings.json file:
If CLAUDE_CODE_GIT_BASH_PATH is set to the correct path and the file exists but Claude Code still doesn’t use it, check the file’s name first. Claude Code accepts only a file named bash.exe, sh.exe, bash, or sh; with any other name, such as Git for Windows’ git-bash.exe launcher, it ignores the variable and auto-detects Git Bash as if it were unset, logging a warning visible with --debug. A path that doesn’t exist gets the same fallback and warning. Before v2.1.219, Claude Code used any existing file as the shell without checking its name, and exited at startup with Claude Code was unable to find CLAUDE_CODE_GIT_BASH_PATH path when the path didn’t exist. If the file’s name is right, endpoint security software such as AppLocker, Group Policy software restriction policies, or EDR agents may be interfering. Ask your IT team to allowlist claude.exe and the processes it spawns, including cmd.exe and bash.exe, in your endpoint protection policy.

​
Claude Code does not support 32-bit Windows

Windows 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:
If this prints True, your operating system is fine. Close the window, open Windows PowerShell without the x86 suffix, and run the install command again. If this prints False, you are on a 32-bit edition of Windows. Claude Code requires a 64-bit operating system. See the system requirements.

​
Linux musl or glibc binary mismatch

If 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.
This can happen on glibc-based systems that have musl cross-compilation packages installed, causing the installer to misdetect the system as musl. Solutions:
  1. Check which libc your system uses:
    Output mentioning GNU libc or GLIBC means glibc. Output mentioning musl means musl.
  2. 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 with the output of ldd --version and ls /lib/libc.musl*.
  3. If you’re actually on musl, such as Alpine Linux, install the required packages:
    On Alpine, ripgrep is in the community repository. If apk reports that the package is missing, see Alpine Linux setup.

​
Illegal instruction

If running claude or the installer prints Illegal instruction, the native binary uses CPU instructions your processor doesn’t support. There are two distinct causes. Architecture mismatch. The installer downloaded the wrong binary, for example x86 on an ARM server. Check with uname -m on macOS or Linux, or $env:PROCESSOR_ARCHITECTURE in PowerShell. If the result doesn’t match the binary you received, file a GitHub issue with the output. Missing AVX instruction set. If your architecture is correct but you still see Illegal instruction, your CPU likely lacks AVX or another instruction the binary requires. This affects roughly pre-2013 Intel and AMD processors, and virtual machines where the hypervisor does not pass AVX through to the guest. On a VPS or VM, run grep -m1 -ow avx /proc/cpuinfo; an empty result means AVX is not available to the guest. There is no native-binary workaround; track issue #50384 for status, and include your CPU model from grep -m1 "model name" /proc/cpuinfo on Linux or sysctl -n machdep.cpu.brand_string on macOS when reporting. Alternative install methods download the same native binary and won’t resolve either cause.

​
dyld: cannot load on macOS

If you see dyld: Symbol not found, dyld: cannot load, or Abort trap: 6 during installation, the binary is incompatible with your macOS version or hardware. A Symbol not found error that references libicucore means your macOS version is older than the binary supports:
The loader can instead reject the binary’s load commands, which also means your macOS version is too old:
Solutions:
  1. 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.
  2. 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.

​
Bus error while a session is running

If a running session exits and your shell prints Bus error, one cause is that Claude Code could no longer read its own executable file from disk. For example, the file was truncated, or deleted on network storage, while the session ran. Before the shell’s message, Claude Code’s runtime can print a crash report that includes panic(main thread): Bus error at address and oh no: Bun has crashed. This indicates a bug in Bun, not your code. When the executable became unreadable, the crash comes from the unreadable file, not from a bug in Bun. The report can also be missing, if the runtime couldn’t read the code that prints it either. Start a new session to continue. If Claude Code is installed on network storage, follow Install on network storage so upgrades don’t remove a binary that running sessions still need.

​
Exec format error on WSL1

If running claude in WSL prints cannot execute binary file: Exec format error, you’re on WSL1 and hitting a known native-binary regression tracked in issue #38788. The binary’s program headers changed in a way WSL1’s loader can’t handle. The cleanest fix is to convert your distribution to WSL2 from PowerShell:
If you need to stay on WSL1, invoke the binary through the dynamic linker. Add this function to ~/.bashrc inside WSL, replacing the path if your home directory differs:
Then run source ~/.bashrc and retry claude.

​
npm install errors in WSL

These issues apply if you installed Claude Code with npm install -g inside WSL. If you used the native installer, skip this section. OS or platform detection issues. If npm reports a platform mismatch during install, WSL is likely picking up the Windows npm. Run npm config set os linux first, then install with npm install -g @anthropic-ai/claude-code --force. Do not use sudo. exec: node: not found when running claude. Your WSL environment is likely using the Windows installation of Node.js. Confirm with which npm and which node: paths starting with /mnt/c/ are Windows binaries, while Linux paths start with /usr/. To fix this, install Node via your Linux distribution’s package manager or via nvm. nvm version conflicts. If you have nvm installed in both WSL and Windows, switching Node versions in WSL may break because WSL imports the Windows PATH by default and the Windows nvm takes priority. The most common cause is that nvm isn’t loaded in your shell. Add the nvm loader to ~/.bashrc or ~/.zshrc:
Or load it in your current session:
If nvm is loaded but Windows paths still take priority, prepend your Linux Node path explicitly:
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.

​
Permission errors during installation

If the native installer fails with permission errors, the target directory may not be writable. See Check directory permissions. If you previously installed with npm and are hitting npm-specific permission errors, switch to the native installer:

​
Native binary not found after npm install

The @anthropic-ai/claude-code npm package downloads the native binary as a per-platform optional dependency, such as @anthropic-ai/claude-code-darwin-arm64. npm then runs the package’s postinstall script, which copies that binary into place as the claude command; until it runs, claude is a placeholder script. If either the download or the postinstall step is skipped, the placeholder stays in place, and running claude on macOS and Linux prints:
On Windows, bin/claude.exe is that same shell-script placeholder rather than a real executable, so PowerShell and CMD report that they can’t run the file instead of printing this message. Check the following causes:
  • 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, and running install.cjs again can’t place a binary that was never downloaded.
  • Install scripts are disabled. --ignore-scripts and some pnpm configurations skip the postinstall step but still download the platform package. Run node node_modules/@anthropic-ai/claude-code/install.cjs as the message suggests, or reinstall without the flag. If postinstall can’t run in your environment at all, node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs finds the downloaded package and launches it, at the cost of an extra Node process on each start. If the wrapper prints Could not find native binary package instead, the platform package was never downloaded, so fix the optional-dependencies cause above first.
  • 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. On FreeBSD, the installer reports the platform as unsupported. Before v2.1.205, it treated FreeBSD as Linux and downloaded a binary that couldn’t run.
  • 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.

​
npm ENOTEMPTY error during update or reinstall

When you run npm install -g @anthropic-ai/claude-code over an existing installation, npm can fail while moving the old package directory aside:
The npm error path line names the directory npm couldn’t move. Delete that directory and any leftover .claude-code-* directories next to it, which earlier interrupted runs can leave behind. The commands below find your global package directory with npm root -g; if the directory the npm error path line names is not under the directory npm root -g prints, for example because you switched Node versions with nvm, delete the directories the error names instead:
Then remove any leftover temp directories. If Zsh prints no matches found, there were none to remove:
Then reinstall:
Confirm with claude --version, which prints a version number such as 2.1.211 (Claude Code).

​
Login and authentication

These sections address login failures, OAuth errors, and token issues.

​
Reset your login

When login fails and the cause isn’t clear, a clean re-authentication resolves most cases:
  1. Run /logout to sign out completely
  2. Close Claude Code
  3. Restart with claude and complete the authentication process again
If the browser doesn’t open automatically during login, press c to copy the OAuth URL to your clipboard, then paste it into a browser manually. This also works when the URL wraps across lines in a narrow or SSH terminal and can’t be clicked directly.

​
OAuth error: Invalid code

If you see OAuth error: Invalid code. Please make sure the full code was copied, the login code expired or was truncated during copy-paste. Solutions:
  • Press Enter to retry and complete the login quickly after the browser opens
  • Type c to copy the full URL if the browser doesn’t open automatically
  • 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.

​
403 Forbidden after login

If you see API Error: 403 Request not allowed after logging in:
  • Claude Pro/Max users: verify your subscription is active at claude.ai/settings
  • Anthropic Console users: confirm your account has the “Claude Code” or “Developer” role. Admins assign this on the Console’s Members page at platform.claude.com/settings/members.
  • Behind a proxy: corporate proxies can interfere with API requests. See network configuration for proxy setup.

​
Claude Code access has not been granted for this account

If the sign-in page shows Authorization failed with the message Claude Code access has not been granted for this account. Contact your administrator. after you log in from Claude Code, your Claude Enterprise organization has set your role to Custom and none of the custom roles assigned to your groups grants Claude Code. On the Custom role, you get access only from those custom roles, so nothing you change in Claude Code resolves this error. To get access:
  1. Ask an Owner of your Claude organization to assign a custom role that grants Claude Code access to one of your groups, or to change your role from Custom to a standard role such as User. Owners manage roles in the organization’s role settings.
  2. After the Owner makes the change, run claude and log in again.

​
This organization has been disabled with an active subscription

If 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. When 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 with the -p flag, the key is always used when present. See authentication precedence for the full resolution order. To use your subscription instead, unset the environment variable and remove it from your shell profile:
Check ~/.zshrc, ~/.bashrc, or ~/.profile for export ANTHROPIC_API_KEY=... lines and remove them to make the change permanent. On Windows, check your PowerShell profile at $PROFILE and your User environment variables for ANTHROPIC_API_KEY. Run /status inside Claude Code to confirm which authentication method is active.

​
OAuth login fails in WSL2, SSH, or containers

When Claude Code runs in WSL2, on a remote machine over SSH, or inside a container, the browser usually opens on a different host and its redirect can’t reach Claude Code’s local callback server. After you sign in, the browser shows a login code instead of redirecting back automatically. Paste that code into the terminal at the Paste code here if prompted prompt to complete login. If the browser doesn’t open at all from WSL2, set the BROWSER environment variable to your Windows browser path:
Alternatively, press c at the interactive login prompt to copy the OAuth URL, or copy the URL that claude auth login prints, and open it in a browser on your local machine. If pasting the code into the interactive prompt does nothing, your terminal’s paste binding likely isn’t reaching the input field. Try your terminal’s alternate paste shortcut, often right-click or Shift+Insert in Windows Terminal, or use claude auth login instead, which reads the pasted code from standard input:
This fallback also applies on native Windows or any terminal where pasting into the interactive prompt fails.

​
Not logged in or token expired

If Claude Code prompts you to log in again after a session, your OAuth token may have expired. Run /login to re-authenticate. If this happens frequently, check that your system clock is accurate, as token validation depends on correct timestamps. Parallel sessions on one machine share a saved login and coordinate its renewal so that only one process refreshes the token at a time. For what the other sessions do after you sign in again in one of them, see Not logged in. Before v2.1.211, waking the machine from sleep could cause two sessions to renew with the same token, which revoked the saved login and prompted every open session to log in again at once. On macOS, Claude Code saves credentials to the login Keychain. When the Keychain rejects the write, such as when it’s locked in an SSH session or its password is out of sync with your account password, Claude Code saves your login to the plaintext ~/.claude/.credentials.json file instead. A Console login that creates an API key fails until the Keychain is writable again. To make the Keychain writable again and move your login back into the encrypted Keychain:
1

Check Keychain access

Run claude doctor to check Keychain access. When the Keychain rejects writes, the report lists a warning that starts with macOS Keychain is not writable, followed by a suggested fix. When the report lists no Keychain warning, the Keychain is writable and you can skip to the last step.
2

Unlock the Keychain

Enter your Keychain password when the command asks for it, then run claude doctor again. When the unlock worked, the report no longer lists the Keychain warning.
3

Resync the Keychain password 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. Then run claude doctor again. Go on to the next step once the report no longer lists the Keychain warning.
4

Log out and back in

Once the Keychain is writable again, Claude Code moves the credentials back the next time it writes a credential. To force it now, run /logout and then /login. Logging out removes all stored credentials, including the plaintext file’s contents, saved MCP server logins, and plugin sensitive values, so expect to re-authorize MCP servers and re-enter plugin secrets afterwards. Logging in again stores your login in the Keychain.

​
Bedrock, Agent Platform, or Foundry credentials not loading

If you configured Claude Code to use a cloud provider and see Could not load credentials from any providers on Amazon Bedrock, Could not load the default credentials on Google Cloud’s Agent Platform, or ChainedTokenCredential authentication failed on Microsoft Foundry, your cloud provider CLI is likely not authenticated in the current shell. For Amazon Bedrock, confirm your AWS credentials are valid:
For Google Cloud’s Agent Platform, confirm ANTHROPIC_VERTEX_PROJECT_ID and CLOUD_ML_REGION are set in your shell, then set application default credentials:
For Microsoft Foundry, confirm ANTHROPIC_FOUNDRY_API_KEY is set, or sign in with the Azure CLI so the default credential chain can find your account:
If credentials work in your terminal but not in the VS Code or JetBrains extension, the IDE process likely didn’t inherit your shell environment. Set the provider environment variables in the IDE’s own settings, or launch the IDE from a terminal where they’re already exported. See Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry for full provider setup.

​
Still stuck

If none of the above resolves your issue:
  1. Check the GitHub repository for known issues, or open a new one with your operating system, the install command you ran, and the full error output
  2. If claude --version works but something else is wrong, run claude doctor for an automated diagnostic report
  3. If you can start a session, use /feedback inside Claude Code to report the problem
  4. If the problem is with your account rather than the install, such as a login loop, a subscription that isn’t recognized, or a disabled organization, contact Anthropic support: sign in at claude.ai (Console users: platform.claude.com), click your initials in the lower left, and select Get help. See How to get support for the full flow.