214 lines
4.4 KiB
Markdown
214 lines
4.4 KiB
Markdown
---
|
|
name: troubleshooting
|
|
description: Common issues and solutions for Claude Code installation, authentication, performance, and IDE integration. Use when user encounters errors, problems, or asks about debugging.
|
|
---
|
|
|
|
# Claude Code Troubleshooting
|
|
|
|
## Installation Issues
|
|
|
|
### Windows WSL Problems
|
|
|
|
**OS/platform detection issues:**
|
|
May require running `npm config set os linux` before installation.
|
|
|
|
**Node.js path conflicts:**
|
|
WSL may use Windows npm instead of Linux versions.
|
|
- Check with `which npm` and `which node`
|
|
- Identify whether Linux or Windows paths are active
|
|
- nvm version conflicts can be resolved by ensuring nvm loads in shell configuration files
|
|
|
|
**Recommended Solution:**
|
|
Use the native Claude Code installer as an alternative to npm:
|
|
```bash
|
|
curl -fsSL https://claude.ai/install.sh | bash
|
|
```
|
|
|
|
### Linux/Mac Permission Errors
|
|
|
|
**Native installer (recommended):**
|
|
```bash
|
|
curl -fsSL https://claude.ai/install.sh | bash
|
|
```
|
|
|
|
**Migration from npm:**
|
|
Migrate to local installation to avoid future permission issues:
|
|
```bash
|
|
claude migrate-installer
|
|
```
|
|
|
|
## Authentication & Permissions
|
|
|
|
### Reset Authentication
|
|
|
|
Run `/logout` and restart Claude Code to reset authentication.
|
|
|
|
For persistent issues, remove stored auth data:
|
|
```bash
|
|
rm -rf ~/.config/claude-code/auth.json
|
|
```
|
|
|
|
### Manage Permissions
|
|
|
|
Use `/permissions` to allow specific tools without repeated approval prompts.
|
|
|
|
## Performance Issues
|
|
|
|
### Reduce Context Size
|
|
|
|
Use `/compact` regularly to reduce context size for large codebases.
|
|
|
|
### Cancel Unresponsive Operations
|
|
|
|
Press `Ctrl+C` to cancel unresponsive operations.
|
|
|
|
### Fix Search Functionality
|
|
|
|
Install system `ripgrep` to fix search functionality:
|
|
```bash
|
|
# macOS
|
|
brew install ripgrep
|
|
|
|
# Ubuntu/Debian
|
|
sudo apt install ripgrep
|
|
|
|
# Fedora
|
|
sudo dnf install ripgrep
|
|
```
|
|
|
|
## IDE Integration Issues
|
|
|
|
### JetBrains on WSL2
|
|
|
|
**Firewall Issues:**
|
|
Configure Windows Firewall or enable mirrored networking mode.
|
|
|
|
Add to `.wslconfig`:
|
|
```ini
|
|
[wsl2]
|
|
networkingMode=mirrored
|
|
```
|
|
|
|
### ESC Key Not Working (JetBrains)
|
|
|
|
Go to Settings → Tools → Terminal and disable "Move focus to the editor with Escape."
|
|
|
|
Or delete the "Switch focus to Editor" shortcut.
|
|
|
|
## Markdown Issues
|
|
|
|
### Missing Language Tags
|
|
|
|
Request language tags explicitly:
|
|
```
|
|
"Add appropriate language tags to all code blocks."
|
|
```
|
|
|
|
### Automatic Formatting
|
|
|
|
Use formatting hooks for automatic post-processing validation.
|
|
|
|
## Common Error Messages
|
|
|
|
### "Command not found: claude"
|
|
|
|
**Solution:**
|
|
1. Verify installation: `npm list -g @anthropic-ai/claude-code`
|
|
2. Check PATH includes npm global bin directory
|
|
3. Restart terminal
|
|
4. Reinstall if necessary
|
|
|
|
### "Authentication failed"
|
|
|
|
**Solution:**
|
|
1. Run `/logout` then `/login`
|
|
2. Verify API key is valid
|
|
3. Check network connectivity
|
|
4. Remove auth file: `rm -rf ~/.config/claude-code/auth.json`
|
|
|
|
### "Permission denied"
|
|
|
|
**Solution:**
|
|
1. Check file permissions in project directory
|
|
2. Verify user has write access
|
|
3. Use `/permissions` to configure allowed operations
|
|
4. Check settings.json for overly restrictive deny rules
|
|
|
|
### "Context too large"
|
|
|
|
**Solution:**
|
|
1. Run `/compact` to reduce context
|
|
2. Be more specific in queries
|
|
3. Use subagents for isolated tasks
|
|
4. Clear conversation with `/clear`
|
|
|
|
### "Rate limit exceeded"
|
|
|
|
**Solution:**
|
|
1. Wait before retrying
|
|
2. Check API usage limits
|
|
3. Use `--max-turns` to limit operations
|
|
4. Implement delays in automation scripts
|
|
|
|
## Getting Help
|
|
|
|
### Built-in Diagnostics
|
|
|
|
**Report bugs:**
|
|
```
|
|
/bug
|
|
```
|
|
|
|
**Check installation health:**
|
|
```
|
|
/doctor
|
|
```
|
|
|
|
### External Resources
|
|
|
|
- **GitHub Issues**: https://github.com/anthropics/claude-code/issues
|
|
- **Documentation**: https://docs.claude.com/en/docs/claude-code
|
|
- **Community Support**: Check GitHub Discussions
|
|
|
|
## Debug Mode
|
|
|
|
Enable verbose logging:
|
|
```bash
|
|
claude --debug
|
|
claude --verbose
|
|
```
|
|
|
|
View detailed output:
|
|
```bash
|
|
claude --output-format json
|
|
```
|
|
|
|
## Reinstallation
|
|
|
|
If all else fails, completely reinstall:
|
|
|
|
```bash
|
|
# Uninstall
|
|
npm uninstall -g @anthropic-ai/claude-code
|
|
|
|
# Clear cache
|
|
rm -rf ~/.config/claude-code
|
|
rm -rf ~/.claude
|
|
|
|
# Reinstall
|
|
npm install -g @anthropic-ai/claude-code
|
|
|
|
# Or use native installer
|
|
curl -fsSL https://claude.ai/install.sh | bash
|
|
```
|
|
|
|
## Prevention Tips
|
|
|
|
1. Keep Claude Code updated: `claude update`
|
|
2. Regularly run `/compact` for large projects
|
|
3. Use specific queries rather than vague requests
|
|
4. Configure permissions appropriately
|
|
5. Monitor API usage and costs
|
|
6. Use version control for important changes
|
|
7. Enable checkpointing for easy recovery
|