Troubleshooting

Installation Issues

"command not found: claude"

Problem: After installing, claude command isn't recognised.

Solutions:

npm config get prefix

echo $PATH

export PATH="$(npm config get prefix)/bin:$PATH"

source ~/.zshrc

npm config get prefix

export PATH="$(npm config get prefix)/bin:$PATH"
source ~/.bashrc

"EACCES: permission denied"

Problem: npm install fails with permission errors.

Solution: Don't use sudo for global installs. Instead, fix npm permissions:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

Node.js version too old

Problem: "Requires Node.js 18+" error.

Solution:

# Check current version
node --version

# Install nvm if needed
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node 20
nvm install 20
nvm use 20

Authentication Issues

"Invalid API key"

Causes:

• Typo in the API key
• Key has been revoked/rotated
• Using wrong key type

Fix:

1. Verify at console.anthropic.com that the key is active
2. Re-enter:

export ANTHROPIC_API_KEY="sk-ant-..."
claude

"Rate limit exceeded"

Problem: Too many requests in a short period.

Solutions:

• Wait a few minutes and retry
• Check your plan limits at console.anthropic.com
• Use /cost to track usage
• Use Claude Pro/Max for higher limits

OAuth flow not completing

Problem: Browser authentication doesn't redirect back.

Solutions:

• Check your browser isn't blocking popups
• Try a different browser
• Check if localhost:PORT is blocked by a firewall
• Manually copy the auth token if shown in the browser

Runtime Issues

Claude is slow to respond

Possible causes:

• Large files being read (check with /cost)
• Network latency
• API load

Solutions:

• Use /compact to reduce context
• Start a fresh session
• Check status.anthropic.com for API status
• Try a faster model (Sonnet instead of Opus)

Claude gives wrong/outdated information

Possible causes:

• Outdated knowledge about new library versions
• Context window filled with stale information
• Hallucination

Solutions:

• Specify versions explicitly: "We use React 19, not 18"
• Point to documentation: "Check the README in node_modules/[lib]"
• Use web search MCP for current documentation
• Start a fresh session if context is polluted

Claude keeps making the same mistake

Possible causes:

• Missing information in CLAUDE.md
• Conflicting instructions
• Pattern not established in codebase

Solutions:

1. Add the correct pattern to CLAUDE.md
2. Show an example: "Do it like src/existing/example.ts"
3. Add to "Do NOT" list in CLAUDE.md
4. Be more explicit in your constraint

"Context window full" / quality degrading

Symptoms:

• Responses get shorter and more generic
• Claude forgets earlier decisions
• Instructions from early messages are ignored

Solutions:

• /compact — summarise and free space
• Start a fresh session for the next task
• Break large tasks into smaller sessions
• Front-load critical context in your first message

File Operation Issues

Claude creates file in wrong location

Fix: Be explicit about paths:

> Create the file at src/components/auth/LoginForm.tsx (not src/LoginForm.tsx)

Or add to CLAUDE.md:

## File Locations
- Components go in src/components/[feature]/
- API routes go in src/api/
- Types go in src/types/

Edits conflict with uncommitted changes

Problem: Claude's proposed edit doesn't apply cleanly.

Solutions:

• Commit or stash your current changes first
• Tell Claude about your uncommitted changes
• Use git diff to show Claude what's already modified

Claude can't find a file

Possible causes:

• File path is wrong
• File is in a different directory than expected
• File is gitignored

Fix:

> The file is at [exact path]. Can you read it?

MCP Issues

MCP server not connecting

Checklist:

1. Is the server command correct? Try running it manually
2. Are environment variables set?
3. Is the package installed? (npx should handle this)
4. Check Claude's MCP status: look for connection messages on startup

MCP tools not appearing

Fix:

• Restart Claude Code after changing MCP config
• Check JSON syntax in settings.json (trailing commas break it)
• Verify the server name matches what you expect

MCP authentication failures

Fix:

• Verify tokens/API keys are valid
• Check token scope (does it have the required permissions?)
• Try the token manually: curl -H "Authorization: Bearer TOKEN" URL

Performance Tips