# Troubleshooting

Common problems during your first Claude Code session and how to fix them.

## Installation Issues

### "command not found" after installing

Close your terminal completely and open a new one. The installer adds Claude Code to your PATH, but the current session does not pick it up.

If that does not work:
1. Check if the binary exists: `ls ~/.claude/local/bin/claude`
2. Add it to your PATH manually: `export PATH="$HOME/.claude/local/bin:$PATH"`
3. Add that line to your `~/.zshrc` (Mac) or `~/.bashrc` (Linux) to make it permanent

### Windows: curl command fails

Use the Windows package manager instead:

```powershell
winget install Anthropic.ClaudeCode
```

Or download the [desktop app](https://claude.ai/download) to skip the terminal entirely.

### "Permission denied" on Mac/Linux

Run with explicit permissions:

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

If that fails, try:

```bash
curl -fsSL https://claude.ai/install.sh -o install.sh
chmod +x install.sh
./install.sh
```

## Authentication Issues

### Browser does not open for sign-in

1. Copy the URL that Claude Code prints in the terminal
2. Paste it into your browser manually
3. Complete the sign-in and return to the terminal

### "Not authenticated" error

Run `claude auth login` and complete the browser sign-in again.

## During Your Session

### Claude Code seems stuck or takes a long time

It is thinking. Complex tasks can take 30-60 seconds. If it has been more than two minutes with no output, press `Ctrl+C` to cancel and try again with a simpler prompt.

### The generated app does not work

Tell Claude Code what is wrong. Be specific:
- "The add button does nothing when I click it"
- "Tasks are not saved when I refresh the page"
- "The dark mode background is white instead of dark"

Claude Code will read the file, find the bug, and fix it.

### Claude Code asks permission for everything

This is normal and good. It asks before creating files and running commands. Type `y` to approve.

If you want fewer prompts, press `Shift+Tab` to switch to a faster permission mode. But for your first session, keep the default mode so you can see exactly what it does.

### "Context window limit" warning

Your session is getting long. Start a new one:

1. Type `/clear` to reset the conversation
2. Or exit with `Ctrl+C` and run `claude` again

Your files are saved on disk. A new session reads them fresh.

## Still Stuck?

Describe your problem to Claude Code itself. Paste the error message and ask what went wrong. It usually knows.