Initial commit
This commit is contained in:
Zhongwei Li
213
skills/troubleshooting/SKILL.md
Normal file
213
skills/troubleshooting/SKILL.md
Normal file
@@ -0,0 +1,213 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user