Troubleshooting
Solutions to common Claude Code issues and how to resolve them
title: Troubleshooting description: Solutions to common Claude Code issues and how to resolve them
Having issues with Claude Code? This guide covers common problems and their solutions to get you back on track quickly.
Installation Issues
Command Not Found
If you get "command not found" after installing Claude Code:
Solution 1: Check your PATH
Solution 2: Verify installation location
Solution 3: Reinstall globally
Permission Denied Errors
When npm install fails with EACCES errors:
Solution: Fix npm permissions
Node.js Version Issues
If you see errors about unsupported Node.js versions:
Authentication Problems
Login Failures
If claude auth login fails or times out:
Check network connectivity:
Clear cached credentials:
API Key Issues
If you're using an API key instead of OAuth:
Session Expiration
If your session keeps expiring:
Runtime Errors
Out of Memory
If Claude Code crashes with memory errors:
Increase Node.js memory limit:
For large codebases:
Use .claudeignore to exclude unnecessary files:
Slow Performance
If Claude Code is running slowly:
1. Check file count:
2. Reduce context size:
3. Clear cache:
Connection Timeouts
If requests time out frequently:
Configuration Issues
Settings Not Applied
If changes to .claude/settings.json don't take effect:
1. Validate JSON syntax:
2. Check file permissions:
3. Restart Claude Code:
MCP Server Connection Failures
If MCP servers won't connect:
1. Check server configuration:
2. Test the server manually:
3. Check for port conflicts:
Custom Commands Not Working
If slash commands don't appear:
1. Check file location:
2. Verify file format:
IDE Integration Issues
VS Code Extension Problems
Extension not loading:
Extension can't find Claude CLI:
Terminal Issues in IDE
Terminal not responding:
- Kill any stuck Claude processes:
-
Restart the integrated terminal
-
Check terminal profile settings in IDE
Platform-Specific Issues
macOS
Gatekeeper blocking execution:
Keychain access issues:
Linux
Missing dependencies:
Windows (WSL)
WSL clipboard issues:
Path issues:
Getting Help
Diagnostic Information
Collect this information before seeking help:
Where to Get Help
- GitHub Issues: github.com/anthropics/claude-code/issues↗
- Discord Community: discord.gg/anthropic↗
- Documentation: docs.anthropic.com↗
Reporting Bugs
When reporting issues, include:
- What you were trying to do
- The exact error message
- Steps to reproduce
- Your environment (OS, Node version, Claude version)
- Relevant configuration files (redact sensitive data)
Quick Fixes Checklist
Before diving deep, try these quick fixes:
- [ ] Restart Claude Code
- [ ] Update to latest version:
npm update -g @anthropic-ai/claude-code - [ ] Clear cache:
rm -rf ~/.claude/cache - [ ] Re-authenticate:
claude auth logout && claude auth login - [ ] Check network:
curl https://api.anthropic.com/v1/health - [ ] Verify configuration:
claude config show