Claude Code Install & Login Errors: Step-by-Step Fix Guide

If you've just installed Claude Code but something isn't working — command not found in the terminal, a 403 error on the login screen, or the install command producing nothing at all — this guide walks you through every common fix in order. The steps below are based on the official troubleshooting documentation at code.claude.com, rewritten so that no prior technical knowledge is assumed. Most issues resolve in 5–15 minutes.

Before You Start: Prerequisites

• Account: A Claude.ai account or an Anthropic API key
• OS: macOS, Linux, or Windows (requires Git for Windows bash or PowerShell). 32-bit Windows is not supported.
• Terminal: macOS/Linux default terminal; Windows: PowerShell or Git Bash
• Internet: Access to downloads.claude.ai must not be blocked

Quick Glossary

• PATH — environment variable: The list of folders your terminal searches when you type a command. If the install folder isn't on this list, the terminal says command not found.
• OAuth — open authorisation protocol: A login method that uses a short-lived permission token instead of sending your password directly.
• curl — command-line download tool: A terminal command used to fetch files from a web address or check a server's response.
• TLS/SSL — transport encryption: The technology that encrypts data in transit. Corporate networks that use their own certificates can trigger TLS errors.

Step 1: Check Network Connectivity

Claude Code downloads from downloads.claude.ai. The first thing to confirm is that your machine can actually reach that server.

On macOS or Linux:

curl -sI https://downloads.claude.ai/claude-code-releases/latest

On Windows PowerShell: PowerShell maps curl to a different built-in command that rejects these flags, so use the explicit binary name:

curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

Success looks like: The first line of the response reads HTTP/2 200.

If you see an error: Could not resolve host or a connection timeout means the server is being blocked — by a firewall, proxy, or VPN. On a corporate or school network, ask your IT team to allow downloads.claude.ai.

Step 2: Install Script Returns HTML

If the terminal shows syntax error near unexpected token '<' right after running the install command, the script has downloaded an HTML error page instead of the actual installer. According to the official documentation, this typically happens when the download server is blocked for your region. Claude Code is not available in all countries — check the supported countries list on the official site.

Step 3: command not found: claude — Fixing PATH

If the install appeared to succeed but typing claude produces command not found, the install directory hasn't been registered in PATH.

1. Open a new terminal window and try again. PATH changes made during installation don't apply to an already-open terminal session. A fresh window fixes this in many cases.
2. If that doesn't help, check whether the install directory is already in PATH by running:

   which claude   # macOS · Linux
   where claude   # Windows PowerShell

   If a path prints out, the command is registered. If nothing prints, continue below.
3. On macOS or Linux, add the install directory to PATH by editing your shell configuration file (~/.zshrc or ~/.bashrc) and appending the following line. Replace [install-path] with your actual install directory.

   export PATH="$PATH:[install-path]"

   Then run source ~/.zshrc (or source ~/.bashrc), or open a new terminal.
4. On Windows PowerShell, add the install directory to your system PATH, then open a new PowerShell window. To edit system PATH, search for Edit the system environment variables in the Start menu.

Step 4: curl Error Types and Fixes

• curl: (56) Failure writing output to destination — Either disk space is full or the target folder has restricted write permissions. Check available storage and folder permissions.
• TLS or SSL connection error — Your CA certificate bundle may be outdated, or a corporate proxy is intercepting the connection. On Ubuntu/Debian, try reinstalling CA certificates with your package manager. The exact command varies by distribution, so confirm the package name on your system.
• curl: (22) The requested URL returned error: 403 — The install script itself returned a 403. According to the official documentation, this is most often caused by a regional restriction or network block.

Step 5: Homebrew Install Error (macOS)

If you see Cask 'claude-code' is unavailable: No Cask with this name exists, Homebrew's local cache is stale. Update it and retry:

brew update
brew install --cask claude-code

Step 6: Windows-Specific Install Errors

• 'bash' is not recognized as the name of a cmdlet — You ran a bash-style install command in PowerShell. According to the official documentation, Windows requires either Git for Windows (bash) or the PowerShell-specific install command. Check the exact command at code.claude.com.
• The process cannot access the file because it is being used by another process — A temporary file from a previous install attempt is still locked. Delete the related temporary files from your Downloads folder, then retry.
• PowerShell install completes but claude is not found: Add the install directory to PATH and open a new PowerShell window.
• 32-bit Windows: Claude Code does not support 32-bit Windows. When searching for PowerShell in the Start menu, use the standard entry — not the one labelled (x86).

Step 7: Login and Authentication Errors

OAuth Error or 403 Forbidden After Login

1. Reset your login: According to the official documentation, clearing stored credentials and signing in again is the fastest first step.

   claude logout
   claude login

2. 403 Forbidden with an active subscription: This can indicate that access has been disabled at the organisation level. Verify your subscription status at claude.com and, if you're on an organisational plan, contact your admin.
3. OAuth login fails in WSL2, SSH, or containers: These environments can't complete a browser redirect. The official documentation recommends switching to API key authentication in this case. See the authentication section at code.claude.com for the exact configuration steps.
4. Bedrock, Vertex, or Foundry credentials not loading (Could not load credentials from any providers, ChainedTokenCredential authentication failed, etc.): Cloud provider credentials are missing or misconfigured. Check the relevant credential file or environment variables for your platform.

Step 8: Linux-Specific Issues

• Install killed on a low-memory server: On servers with very little RAM, the install process can be terminated mid-way. The official documentation recommends adding swap space. The exact commands differ by distribution, so verify the steps for your system.
• musl/glibc binary mismatch (Error loading shared library): The downloaded binary was built for glibc but your system (e.g. Alpine Linux) uses musl. Check the official documentation for the correct binary variant for your distribution.
• Illegal instruction: Your CPU does not support the instruction set the binary requires. Verify architecture compatibility in the official documentation.

Still Stuck?

• Use the Claude Code desktop app: According to the official documentation, a graphical desktop app is available for macOS and Windows, letting you install and use Claude Code without any command-line setup. If terminal installation keeps failing, this is the quickest alternative.
• Check the Error Reference page: The Error reference section at code.claude.com covers HTTP status codes such as 500, 529 (overloaded), 429, and other 4xx/5xx errors not listed here.