Claude Code Errors: 5 Common Problems and How to Fix Them Fast (2026)

Claude Code ships updates fast, so command names and behavior can change; I'll flag anything you should double-check yourself. Cross-reference the official Claude Code documentation when you need certainty.

Quick error lookup (symptom → fix)

This is the main reference section. Find the row that matches the message you're seeing, follow the last column, and jump to the detailed section if you want to understand the cause.

Before you fix anything: your problem or Anthropic's?

The most common beginner mistake is diving straight into reinstalling and rewriting config when the problem actually lives on the server. Before each fix, take 30 seconds to classify it:

• Your side (env/config): command not found, a bad PATH, broken auth, a permission block, a full context. Telltale sign: it repeats consistently, the same message on every run.
• Anthropic's side (you can't fix it): an overloaded message, the model not responding even though your network is fine, an error that shows up out of nowhere when you changed nothing. Telltale sign: it's sudden and usually clears itself in a few minutes.

Three commands to triage fast: claude --version (installed correctly?) → /status (which route am I on, do I have quota left?) → open Anthropic's official status page (any system incident?). If all three are fine and you're still stuck, then it's time to fix your local environment.

Error 1 - Installed, but claude won't run (command not found / PATH)

Symptom. You finished installing, but typing claude gives you one of these messages:

# macOS / Linux (zsh, bash)
zsh: command not found: claude

# Windows (PowerShell / CMD)
claude : The term 'claude' is not recognized as the name of a cmdlet...

The frustrating part: npm reports a successful install, yet the terminal still can't find the command.

Cause. The package landed in npm's global bin folder, but that folder isn't in your PATH environment variable, so the shell has no idea where to find the claude binary. On Windows, an environment variable you set in one window is usually gone the moment you open a new one.

Fix. First, find npm's global bin folder:

npm config get prefix
# e.g. returns: /Users/you/.npm-global (macOS)
# or: C:\Users\you\AppData\Roaming\npm (Windows)

The command lives in PREFIX/bin (macOS/Linux) or in PREFIX itself (Windows). Add it to your PATH:

# macOS / Linux - append to the end of ~/.zshrc (or ~/.bashrc)
export PATH="$(npm config get prefix)/bin:$PATH"
# then reload
source ~/.zshrc

# verify
claude --version

On Windows, open your PowerShell profile and add the equivalent line, or add the npm path to your system PATH variable (Settings → Environment Variables) and then reopen the terminal. But here's my practical recommendation: on Windows, run Claude Code inside WSL2 rather than native PowerShell/CMD - the Linux environment sidesteps nearly all of the fiddly PATH and permission issues specific to Windows.

If it still isn't recognized after you fix the PATH, the odds are the original install wasn't clean. Revisit how to install Claude Code the right way and start over cleanly.

Error 2 - Can't log in / auth failures (API key vs subscription)

Symptom. Login hangs in the browser, reports unauthorized, or Claude Code keeps demanding an API key even though you think you're already signed in with a Pro/Max plan.

Cause. Two sources tend to cause trouble here. One is a corrupted credential cache - an old token stuck in place. The second, and more common, is confusion between two auth routes: signing in with a subscription (a Pro/Max plan via your account) is completely different from using ANTHROPIC_API_KEY (billed per token). If you ever set the ANTHROPIC_API_KEY environment variable, Claude Code may prefer the API-key route and ignore the plan you're paying for.

Fix. Reset your credentials first:

claude logout
claude login # sign in again on the route you want (subscription)

Then check whether an API-key variable is "cutting in line":

# macOS / Linux
echo $ANTHROPIC_API_KEY

# Windows (PowerShell)
echo $env:ANTHROPIC_API_KEY

If you want to use your Pro/Max plan but this variable has a value, remove it from your shell profile (the export ANTHROPIC_API_KEY=... line in .zshrc, or the environment variable on Windows) and reopen the terminal. Finally, run /status inside Claude Code to confirm you're on the right route. Conversely, if you deliberately want to use an API key, make sure it's still valid and has credit.

Error 3 - "Rate limit reached" / 429 error

Symptom. You're running along and it stops mid-task with a Rate limit reached message or a 429 code, sometimes even when you've barely used it.

Cause. The trap is that two different systems report the same line, but the way you handle them is the opposite:

Fix. First identify your route with /status. Then hunt down orphaned processes - Claude Code sometimes leaves a process running in the background after you close the window, and it keeps counting against your quota:

# macOS / Linux - list live claude processes
ps aux | grep claude
# see a stray PID? kill it: kill <PID>

# Windows: open Task Manager, find lingering node/claude processes and end them

If your route is a subscription plan and you genuinely ran out, there's no trick beyond waiting for the window to reset or temporarily switching to a lighter model to conserve usage. With an API key, raising the limit is a matter of your account tier. To know exactly which rule a specific 429 came from, cross-reference the issues in the anthropics/claude-code repo.

Error 4 - Claude Code hangs / stalls mid-task (full context)

Symptom. The session freezes, replies slow to a crawl, the model starts "forgetting" what you said at the start, or it drops into an endless edit-and-re-edit loop that never finishes.

Cause. Usually it's a full context window: you've had a very long conversation, pasted in a huge file, or handed it one task so big the output balloons. This is not a server error - so don't confuse it with an overloaded message on Anthropic's side.

Fix. From lightest to heaviest:

• /compact - compresses the conversation, keeping the key points but freeing up room. Use it when you still want to continue the current line of work.
• /clear - wipes the context and starts fresh. Use it when you're moving to an unrelated task.
• Break the task into sequential pieces. Instead of "refactor the whole module," hand it one file at a time. Prevention beats cure here.
• Avoid pasting an entire oversized file into the chat - let Claude Code read the file itself when needed instead of stuffing it all into context.
• If it's fully frozen: exit the session (Ctrl+C) and reopen. You lose the current context, but it decisively ends the stuck state.

If you want to go deeper on managing context to avoid hangs, the methodical, beginner-friendly workflow in 10 steps to get started with Claude Code will help you hand off work cleanly from the outset.

Error 5 - Blocked by permissions (can't run a command)

Symptom. Claude Code asks for confirmation before every command, or flat-out refuses to run a command / edit a file, interrupting your flow.

Cause. This usually isn't a "bug" - it's a safety feature: the permission mode is blocking a risky operation until you grant access. By default, Claude Code is cautious about commands that could modify/delete files or run a shell.

Fix. Grant access in a controlled way:

• When Claude Code asks, choose per-session access for operations you trust, instead of clicking approve every single time.
• Add frequently used commands to an allowlist so it stops asking.
• Understand the different permission modes so you can pick the level that fits what you're doing.

An honest warning: don't flip on the mode that skips all confirmations just to "go faster." It lets Claude Code run any command without asking - convenient, but a real risk if the model does something you didn't anticipate on an important machine or repo. Only use it in an isolated environment (a sandbox/container).

Safe permission setup has several layers, so I'll spin it out into a dedicated deep-dive on Claude Code permissions and permission modes that you can set once and rely on long-term.

Still hitting small errors? Checklist & when to reinstall

If you've been through all 5 groups above and still catch odd little errors, run this whole checklist before you even think about reinstalling:

• Update to the latest build: npm i -g @anthropic-ai/claude-code - plenty of bugs get fixed in later releases.
• Check that Node is on an LTS version (some baffling errors come from Node being too old or too new).
• Keep one terminal running Claude Code per project to avoid conflicts and orphaned processes.
• Clear the credential cache with claude logout and log back in.
• Clean reinstall: fully uninstall, then reinstall following the Claude Code installation guide.
• Not sure how the tool actually works? Reread what Claude Code is to get the right mental model - many "errors" are really misunderstandings of how it operates.

When to contact Anthropic support: an error that persists even on a clean machine, repeated overloaded messages for hours, or a billing/account issue you can't adjust yourself.

Fewer errors and more power with a prebuilt kit (AgentKit)

A big share of the little errors comes from every machine's environment being different: a skewed PATH, scattered config, missing standard skills or a statusline. If you'd rather stop wrestling with manual configuration, the AgentKit kit for Claude Code ships ready-made config, skills, and even a statusline builder that help standardize your working environment - heading off a lot of the fiddly config errors and keeping sessions more stable. It doesn't "fix" the CLI errors above for you, but it reduces the chances for them to show up in the first place. If you want to try it, you can give AgentKit a spin (20% off via link) and see whether the prebuilt setup fits the way you work.

Frequently asked questions (FAQ)

Why does typing claude report command not found?

Because the folder that holds the command (npm's global bin) isn't in your PATH environment variable, so the shell can't find the binary. Run npm config get prefix, add the matching /bin folder to PATH, then reopen the terminal.

Does Claude Code run on Windows / PowerShell?

It does, but the experience is much smoother with WSL2 than with native PowerShell/CMD. WSL2 avoids most of the PATH and permission issues specific to Windows.

How long does "Rate limit reached" last?

It depends on the source. If it's Pro/Max plan quota, you have to wait for the time window to reset. If it's an API key's RPM/TPM limit, reducing your concurrent requests clears it immediately. Run /status to see which one you've hit.

What do I do when Claude Code hangs?

Usually it's a full context. Use /compact to compress the conversation or /clear to reset, break the task into smaller pieces, and avoid pasting oversized files. If it's fully frozen, exit the session (Ctrl+C) and reopen it.

Is a login error caused by the API key or the plan?

Check the ANTHROPIC_API_KEY variable: if it has a value, Claude Code may take the API-key route instead of the plan you paid for. To use your Pro/Max plan, remove that variable, then claude logout and claude login again.

How do I reinstall Claude Code?

Uninstall the old package, run npm i -g @anthropic-ai/claude-code again, make sure Node is on an LTS version, and confirm npm's global bin folder is in your PATH. Then run claude login from scratch.

Conclusion + next steps

Bottom line: don't fix at random. Classify first - your problem or Anthropic's - then fix by the matching symptom group: won't run/PATH, auth, rate limit, hang/context, or permission. The three commands claude --version, /status, and /compact handle most day-to-day situations. If you're hitting errors right as you install, head back to the Claude Code installation guide; and if you're just starting out and want to avoid errors at the root, follow the 10 steps for beginners. To standardize your environment and cut down on the little errors long-term, take a look at the AgentKit review for Claude Code.