7 min · +100 XP
When the install does not work
The usual error messages and what to do about each.
By the end of this lesson
You will be able to match an install error to its fix without guessing.
Most install problems come down to a few known errors. Find yours by the exact text on the screen, then follow the fix under it. Copy the full error text first: you may need it for a search or a support request.
claude doctor
Run it in the terminal once claude --version works. It prints read-only checks of the install and settings with suggested fixes. Inside a running session, /doctor does a checkup and can apply fixes after you confirm.
"command not found: claude" or "'claude' is not recognized"
The install worked, but the terminal does not know where the program is. First close the terminal and open a new window. If it still fails, the installer printed the fix under Setup notes at the end of its output; run that, or use the line for your system below.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc
Prints nothing when it works. Then open a new window and try claude --version.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc
Prints nothing when it works. Then open a new window and try claude --version.
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')Close PowerShell, open a new window and try claude again.
Windows: "'irm' is not recognized"
Windows: you are in CMD, not PowerShell. Either open PowerShell from the Start menu and run the PowerShell line, or stay in CMD and use the CMD install line from the previous lesson. If you see "The token '&&' is not a valid statement separator", it is the other way round: you are in PowerShell with the CMD line.
Windows: "A parameter cannot be found that matches parameter name 'fsSL'"
Windows: you pasted the Mac and Linux line into PowerShell. Use irm https://claude.ai/install.ps1 | iex instead.
"syntax error near unexpected token '<'"
The installer received a web page instead of the install script; in PowerShell the same problem shows up as errors quoting HTML, or System.Xml.XmlDocument. If the text mentions "App unavailable in region", see the next error. Otherwise wait a few minutes and retry, or install with brew install --cask claude-code (Mac) or winget install Anthropic.ClaudeCode (Windows).
"App unavailable in region"
Claude Code is not available in your country. The list is at anthropic.com/supported-countries. This course does not describe ways around the restriction.
A work computer blocks the install
Company computers often block downloads through a proxy or firewall; typical signs are a 403 error, "unable to get local issuer certificate" or no connection at all. Ask your IT team: they can allow downloads.claude.ai or give you the proxy settings. Do not try to get around company security, and use a personal computer for the course if IT says no.
An old system
Claude Code needs macOS 13.0 or later, or Windows 10 version 1809 or later, and 4 GB of memory or more. On an older Mac you see errors such as "dyld: cannot load" or "built for Mac OS X 13.0"; update macOS through Software Update if your Mac allows it.
Windows: "Could not create SSL/TLS secure channel"
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 irm https://claude.ai/install.ps1 | iex
This happens on older Windows 10 systems. The first line switches PowerShell to a newer secure connection, the second runs the installer again.
Windows: "Claude Code does not support 32-bit Windows"
Windows: on a 64-bit computer this means you opened Windows PowerShell (x86). Close it, open the Start menu entry without (x86) in its name and run the install again.
The full list of errors is at code.claude.com/docs/en/troubleshoot-install. You can also paste the error into the Claude app or claude.ai and ask what it means. If the terminal still will not cooperate, the desktop app is another way to start.
“I am installing Claude Code and got this error: [paste the full error text]. My computer is [Mac / Windows / Linux]. What does it mean, and what exactly should I paste or click to fix it?”
Ask this in the Claude app or on claude.ai, since Claude Code itself is not running yet. Replace the parts in brackets.
Once claude starts, you no longer need to fix anything by hand. Ask Claude Code itself.
“Check that my Claude Code install is healthy: run the checks, explain anything that looks wrong and fix it with my approval.”
Claude runs the checks, explains what it finds and asks before changing settings.
On Windows you see "'irm' is not recognized as an internal or external command". What is wrong?
The installer printed "Claude Code successfully installed!", but claude is not found. What is the first thing to try?
Facts checked against the official Claude Code docs October 24, 2026 · source
Author
Evgenii Arsentev
PhD · Chief Executive Officer, digital health