# Troubleshooting

> Discover solutions to common issues with Claude Code installation and usage.

## Common Installation Issues

### Windows Installation Issues (WSL)

**OS/platform detection issues**: If you receive an error during installation, WSL may be using Windows `npm`. Try:
- Run `npm config set os linux` before installation
- Install with `npm install -g @anthropic-ai/claude-code --force --no-os-check` (Do NOT use `sudo`)

**Node not found errors**: If you see `exec: node: not found`, your WSL environment may be using Windows Node.js. Confirm with `which npm` and `which node` (should point to `/usr/` paths, not `/mnt/c/`). Install Node via your Linux distribution's package manager or via `nvm`.

**nvm version conflicts**: If you have nvm installed in both WSL and Windows:
1. Check `which npm` and `which node` - if pointing to `/mnt/c/`, Windows versions are being used
2. Add to your shell configuration:
```bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
```

### WSL2 Sandbox Setup

If you see "Sandbox requires socat and bubblewrap":
```bash
# Ubuntu/Debian
sudo apt-get install bubblewrap socat

# Fedora
sudo dnf install bubblewrap socat
```

WSL1 does not support sandboxing.

### Linux and Mac: Permission or Command Not Found Errors

**Recommended solution**: Use the native Claude Code installation:

**macOS, Linux, WSL:**
```bash
# Install stable version
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
```

**Windows PowerShell:**
```powershell
# Install stable version
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest
```

### Windows: "Claude Code on Windows requires git-bash"

Claude Code on native Windows requires Git for Windows. If Git is installed but not detected:

```powershell
$env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"
```

### Windows: "installMethod is native, but claude command not found"

Add to your PATH:
1. Press `Win + R`, type `sysdm.cpl`, press Enter
2. Click **Advanced** -> **Environment Variables**
3. Under "User variables", select **Path** and click **Edit**
4. Add: `%USERPROFILE%\.local\bin`
5. Restart your terminal

## Permissions and Authentication

### Repeated Permission Prompts

Allow specific tools to run without approval using `/permissions`. See permission settings documentation.

### Authentication Issues

1. Run `/logout` to sign out completely
2. Close Claude Code
3. Restart with `claude` and complete authentication again

If the browser doesn't open, press `c` to copy the OAuth URL.

If problems persist:
```bash
rm -rf ~/.config/claude-code/auth.json
claude
```

## Configuration File Locations

| File                          | Purpose                                                  |
| :---------------------------- | :------------------------------------------------------- |
| `~/.claude/settings.json`     | User settings (permissions, hooks, model overrides)      |
| `.claude/settings.json`       | Project settings (checked into source control)           |
| `.claude/settings.local.json` | Local project settings (not committed)                   |
| `~/.claude.json`              | Global state (theme, OAuth, MCP servers)                 |
| `.mcp.json`                   | Project MCP servers (checked into source control)        |
| `managed-settings.json`       | Managed settings                                         |
| `managed-mcp.json`            | Managed MCP servers                                      |

**Managed file locations:**
- macOS: `/Library/Application Support/ClaudeCode/`
- Linux/WSL: `/etc/claude-code/`
- Windows: `C:\Program Files\ClaudeCode\`

### Resetting Configuration

```bash
# Reset all user settings and state
rm ~/.claude.json
rm -rf ~/.claude/

# Reset project-specific settings
rm -rf .claude/
rm .mcp.json
```

**Warning**: This removes all settings, MCP server configurations, and session history.

## Performance and Stability

### High CPU or Memory Usage

1. Use `/compact` regularly to reduce context size
2. Close and restart Claude Code between major tasks
3. Consider adding large build directories to `.gitignore`

### Command Hangs or Freezes

1. Press Ctrl+C to attempt to cancel the current operation
2. If unresponsive, close the terminal and restart

### Search and Discovery Issues

If Search tool, `@file` mentions, custom agents, and custom skills aren't working, install system `ripgrep`:

```bash
# macOS (Homebrew)
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep
```

Then set `USE_BUILTIN_RIPGREP=0` in your environment.

### Slow or Incomplete Search Results on WSL

Disk read performance penalties when working across file systems on WSL may result in fewer-than-expected matches.

**Solutions:**
1. Submit more specific searches
2. Move project to Linux filesystem (`/home/`)
3. Consider running Claude Code natively on Windows

## IDE Integration Issues

### JetBrains IDE Not Detected on WSL2

**Option 1: Configure Windows Firewall** (recommended)
```bash
# Find your WSL2 IP
wsl hostname -I

# In PowerShell as Administrator:
New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
```

**Option 2: Switch to mirrored networking**

Add to `.wslconfig` in your Windows user directory:
```ini
[wsl2]
networkingMode=mirrored
```

Then restart WSL with `wsl --shutdown`.

### Escape Key Not Working in JetBrains Terminals

1. Go to Settings -> Tools -> Terminal
2. Either:
   - Uncheck "Move focus to the editor with Escape", or
   - Click "Configure terminal keybindings" and delete the "Switch focus to Editor" shortcut

## Markdown Formatting Issues

### Missing Language Tags in Code Blocks

**Solutions:**
1. Ask Claude to add language tags: "Add appropriate language tags to all code blocks in this markdown file."
2. Use post-processing hooks
3. Manual verification after generating markdown

### Inconsistent Spacing and Formatting

**Solutions:**
1. Request formatting corrections
2. Set up hooks to run formatters like `prettier`
3. Specify formatting preferences in CLAUDE.md

## Getting More Help

1. Use `/bug` to report problems directly to Anthropic
2. Check the [GitHub repository](https://github.com/anthropics/claude-code) for known issues
3. Run `/doctor` to diagnose issues. It checks:
   - Installation type, version, and search functionality
   - Auto-update status and available versions
   - Invalid settings files (malformed JSON, incorrect types)
   - MCP server configuration errors
   - Keybinding configuration problems
   - Context usage warnings (large CLAUDE.md files, high MCP token usage)
   - Plugin and agent loading errors
4. Ask Claude directly about its capabilities - Claude has built-in access to its documentation

## Grid Integration Opportunities

<!-- Placeholder for Grid-specific integration notes -->