Troubleshooting

Something's broken. Let's fix it. Here's what I've seen come up most often, and the shortest path to each solution.

Installation Problems

"npm: command not found"

Node.js isn't installed. npm comes bundled with Node.js, so you need Node first.

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

On Mac with Homebrew:

brew install node

"EACCES: permission denied"

npm is trying to write files somewhere your user account can't access. Very common on Mac and Linux, annoying but easy to fix.

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 again:

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

Then add the new directory to your PATH. For bash:

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

For zsh (default on newer Macs):

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

Now reinstall without sudo.

Windows: Open 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 the claude binary lives. 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 it and add that to your PATH:

npm config get prefix

This prints a path like /usr/local or ~/.npm-global. The claude binary lives in the bin folder inside that path.

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 expired or was never completed.

Fix:

claude auth login

This opens a browser window where you sign in with your Anthropic account. Follow the prompts.

"You need a paid plan"

Claude Code isn't included in the free Anthropic tier.

Fix: Sign up at claude.ai. Claude Pro ($20/month) works well for most people. Claude Max ($100/month) gives you much higher daily limits if you're hitting Pro's ceiling. After subscribing, run claude auth login to re-authenticate.

Session Expired Mid-Work

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

Fix: Run claude auth login to get a fresh session. Your actual work is safe because Claude Code edits your local files directly, it doesn't hold your code hostage.

Performance Problems

"Rate limit reached"

You've hit your plan's usage quota. More common on Pro during heavy-use days.

Fix: Wait for the limit to reset (usually daily). While you wait:

• Run /compact to compress your conversation history and reduce context per request
• Start fresh sessions for new tasks instead of continuing a long running one
• Write more specific prompts so Claude Code doesn't need multiple rounds to understand what you want
• Upgrade to Max ($100/month) if you consistently hit limits. You'll know it's time when it starts frustrating you.

"Claude Code is slow"

Long conversations accumulate a large context window, which makes each response slower to generate. This is the most common source of sluggishness.

Fix:

• Start a new session when switching to a different task. Each fresh session is fast.
• Run /compact to reduce context size without losing important information. I do this every 30-40 minutes in long sessions.
• Write a handoff document before ending a session, then start fresh next time. Warm starts are faster than bloated old sessions.

Response Gets Cut Off

Context window is full. Claude Code ran out of room to finish 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 in the new session. Better yet, 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 somewhere else, it won't find them.

Fix: Check your current directory before starting:

pwd

Navigate to your project folder, then start Claude Code:

cd /path/to/your/project
claude

Claude Modified the Wrong File

Happens when your project has similarly named files in different directories.

Fix: Be specific in your prompts. Instead of "update the config file," say "update src/config/database.ts." Full file paths remove all ambiguity.

To undo unwanted changes:

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

Changes Disappeared

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

Fix: Check git status first:

git status
git diff

If changes are still there but unstaged, you're fine. If they're gone, check git reflog. Sometimes you can recover from there.

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

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

Getting More Help

None of the above fixed it:

• Anthropic's official docs: latest setup and usage guides, updated more frequently than any third-party site
• GitHub Issues: where actual bugs are tracked. Search for your error message before filing a new one.
• Anthropic Discord: community of Claude Code users. If you've hit a weird edge case, someone else probably has too.