---

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:

Copycurl -fsSL https://claude.ai/install.sh | bash

Linux/Mac Permission Errors

Native installer (recommended):

Copycurl -fsSL https://claude.ai/install.sh | bash

Migration from npm: Migrate to local installation to avoid future permission issues:

Copyclaude migrate-installer

Authentication & Permissions

Reset Authentication

Run /logout and restart Claude Code to reset authentication.

For persistent issues, remove stored auth data:

Copyrm -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:

Copy# 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:

Copy[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:

Copy"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:

Copy/bug

Check installation health:

Copy/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:

Copyclaude --debug
claude --verbose

View detailed output:

Copyclaude --output-format json

Reinstallation

If all else fails, completely reinstall:

Copy# 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