troubleshooting

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