During installation
"command not found: claude"
You installed Claude Code but the terminal can't find it. Common causes:
- The npm installation didn't complete successfully. Reinstall with: npm install -g @anthropic-ai/claude-code
- npm's global folder isn't in your PATH. Close and reopen your terminal.
- Still stuck: check where npm installs packages with npm config get prefix and make sure that path's /bin directory is in your PATH.
"EACCES: permission denied" when installing
npm doesn't have permission to install globally. Don't use sudo (it causes more problems). Instead, the best approach is to install Node.js with a version manager like nvm, which avoids these permission issues.
"Node.js version too old" / incompatible version
Claude Code requires Node.js 20 or later. Check your version with node --version. If it's older, update Node.js (with nvm: nvm install 20 && nvm use 20).
When signing in / authentication
"Invalid API key" or authentication errors
- Make sure you copied the full key, with no leading or trailing spaces.
- Verify the variable is set correctly: echo $ANTHROPIC_API_KEY should display it.
- If you added it to ~/.zshrc, reload with source ~/.zshrc or open a new terminal.
- The key may have been revoked or exhausted. Generate a new one at console.anthropic.com.
"Rate limit exceeded" / "Too many requests"
You've made too many requests in a short time, or you've hit your plan's limit. Wait a few minutes. If it keeps happening, review your plan limits or, for API usage, your usage tier in the Anthropic dashboard.
"Insufficient credit" / balance depleted
If you're using the API, your credits have run out. Add funds or a payment method at console.anthropic.com. If you're on a subscription, you may have hit your plan's usage limit; wait for it to renew or upgrade your plan.
During use
Claude Code is slow or gets "stuck"
- Very long session: the context has filled up. Use /compact to summarize it, or /clear to start fresh (you'll lose the conversation context, not your files).
- Task too large: break it into smaller pieces. See how to write good prompts.
- Connection: Claude Code needs a stable internet connection.
It makes changes I didn't want
- Use /rewind (or Esc Esc) to undo to the previous state. See Workflows.
- If you use git: git restore . reverts unsaved changes.
- For next time: use Plan Mode (Shift + Tab) and review the plan before it acts.
It doesn't ask for permission / it asks for permission too often
Adjust the permissions list. If it asks about things you always allow (like npm run), add them to the allow list. If you want more control, review your configuration. Everything in Permissions.
A feature from the documentation doesn't show up for me
You probably have an old version. Claude Code updates very frequently:
claude --version npm update -g @anthropic-ai/claude-code
An MCP server won't connect
- Check the list with /mcp inside Claude Code.
- Verify the server command is correct and that it has the required environment variables (tokens, paths).
- See details in MCP Servers.
The catch-all that always works
If you're stuck on any error, ask Claude Code directly. It's literally an expert at solving technical problems. Paste the full error: