Troubleshooting

Something not working? You're probably not the first person to hit this. Here are the most common problems people run into with Claude Code, and the quickest way to fix each one.

Installation Problems

"npm: command not found"

This means Node.js isn't installed on your machine. npm comes bundled with Node.js, so you need to install it first.

Fix: Download and install Node.js from nodejs.org. Pick the LTS version. After installing, close your terminal, open a new one, and try the install command again.

On Mac with Homebrew, you can also run:

brew install node

"EACCES: permission denied"

npm is trying to install files in a folder your user account doesn't have permission to write to. This is very common on Mac and Linux.

Quick fix (Mac): Add sudo before the command:

sudo npm install -g @anthropic-ai/claude-code

Proper fix (Mac and Linux): Change npm's default directory so you never need sudo:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

Then add the new directory to your PATH. If you use bash:

echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

If you use zsh (default on newer Macs):

echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Now run the install command again without sudo.

Windows fix: Make sure you opened PowerShell as Administrator. Right-click PowerShell in the Start menu and choose "Run as Administrator."

"claude: command not found" After Installing

The install succeeded, but your terminal doesn't know where to find the claude command. This is a PATH issue.

Fix 1: Close your terminal and open a new one. Sometimes the PATH just needs a refresh.

Fix 2: Find where npm installed the package and add it to your PATH:

npm config get prefix

This prints a path (like /usr/local or ~/.npm-global). The claude command lives in the bin folder inside that path. Add it to your shell config:

echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Replace .zshrc with .bashrc if you use bash.

Fix 3 (Windows): Restart your computer. Windows sometimes needs a full restart to pick up new PATH entries.

Authentication Problems

"401 Unauthorized"

Your login session has expired or was never completed.

Fix: Re-authenticate by running:

claude auth login

Follow the prompts to log in again. This opens a browser window where you'll sign in with your Anthropic account.

"You need a paid plan"

Claude Code is not included in the free Anthropic tier. You need an active subscription.

Fix: Sign up for a paid plan at claude.ai:

• Claude Pro ($20/month) works well for most users
• Claude Max ($100/month) gives you much higher daily limits

After subscribing, run claude auth login to re-authenticate with your paid account.

Session Expired

If Claude Code suddenly stops working mid-session with an authentication error, your token likely expired.

Fix: Run claude auth login to get a fresh session. Your work in progress is safe because Claude Code operates on your local files.

Performance Problems

"Rate limit reached"

You've hit your plan's usage quota for the current period. This is more common on the Pro plan during heavy use.

Fix: Wait for the limit to reset (usually resets daily). In the meantime, here are ways to use your quota more efficiently:

• Use /compact to compress your conversation history and free up context
• Start fresh sessions for new tasks instead of continuing a long one
• Be specific in your prompts so Claude Code doesn't need multiple rounds to understand what you want
• Upgrade to Max ($100/month) if you consistently hit limits

"Claude Code is slow"

Long conversations build up a large context window, which makes each response take longer to generate.

Fix:

• Start a new session when switching to a different task. Each fresh session is fast.
• Run /compact to reduce the context size without losing important information
• Close unrelated files before asking Claude Code to work on something new
• Write a handoff document before ending a session, then start fresh next time

Response Gets Cut Off

The context window is full. Claude Code ran out of room to generate its response.

Fix: Start a new session. Before you do, ask Claude Code to summarize what it was working on so you can pick up where you left off. Even better, set up a session lifecycle so context carries over automatically.

File and Project Problems

"Claude can't see my files"

Claude Code works in whatever directory you launched it from. If your files are elsewhere, it won't find them.

Fix: Make sure you're in the right folder before starting Claude Code:

pwd

This prints your current directory. Navigate to your project folder first:

cd /path/to/your/project
claude

Claude Modified the Wrong File

If your project has similarly named files, Claude Code might pick the wrong one.

Fix: Be specific in your prompts. Instead of "update the config file," say "update src/config/database.ts." Including the full file path removes any ambiguity.

You can also undo changes with git:

git diff           # See what changed
git checkout -- filename.ts  # Undo changes to a specific file

Changes Disappeared

Claude Code edits files directly, but it does not automatically commit to git. If you ran git checkout or switched branches, your changes might be gone.

Fix: Check your git status to see what happened:

git status
git diff

If changes are still there but unstaged, you're fine. If they're gone, check git reflog to see if they can be recovered.

Prevention: Commit your work frequently. Ask Claude Code to "commit these changes" or do it yourself:

git add -A && git commit -m "work in progress"

Getting More Help

If none of the above solved your problem:

• Anthropic's official docs have the latest setup and usage guides
• GitHub Issues is where bugs and feature requests are tracked. Search for your error message.
• Anthropic Discord has a community of Claude Code users who might have hit the same issue