# Gemini Web MCP CLI - Troubleshooting Guide

## Quick Diagnosis

| Symptom | Likely Cause | Solution |
|---------|-------------|----------|
| "AuthError" or "expired" | Session cookies expired | `gemcli login` |
| "UsageLimitExceeded" (1037) | Too many requests | Wait 1-2 minutes, retry |
| "ModelInvalid" (1050/1052) | Wrong model name or no Token Factory | Check model name, run `gemcli doctor` |
| "TemporarilyBlocked" (1060) | IP rate limited by Google | Wait 5-10 minutes, try VPN |
| Chrome doesn't launch | Port conflict or missing binary | Close Chrome, run `gemcli doctor` |
| TokenFactoryError | Chrome/BotGuard issue | Ensure Chrome installed, check `gemcli doctor --verbose`. Background: `gemcli chrome start` |
| "gemini-web-mcp not found" | Binary not on PATH | `pip install gemini-web-mcp-cli[mcp]` |
| MCP tool returns error | Auth or network issue | Run `gemcli login`, then retry |
| Empty response from chat | Model returned no candidates | Try different model or rephrase prompt |
| Video generates image | Missing BotGuard/tool activation | `gemcli chrome start`, ensure Chrome running |
| Image generation fails | Missing BotGuard/tool activation | `gemcli chrome start`, ensure Chrome running |
| Music generation fails | Chrome/BotGuard or content policy | `gemcli chrome start`, then retry; `gemcli login` if auth error |
| "Unknown music style" | Invalid style preset name | Run `gemcli music --list-styles` for valid names |

---

## Authentication Issues

### Cookies Have Expired

**Symptoms:** Commands fail with `AuthError`, "session expired", or 401-like responses.

**Solution:**
```bash
gemcli login
# Or validate current session:
gemcli login --check
```

### Chrome Doesn't Launch for Login

**Symptoms:** `gemcli login` hangs or errors about Chrome.

**Solutions:**
1. Close all Chrome instances first
2. Check Chrome is installed: `gemcli doctor --verbose`
3. Fall back to manual mode: `gemcli login --manual`

### Manual Cookie Entry

If automated Chrome login fails:

```bash
gemcli login --manual
```

Then extract cookies from Chrome DevTools:
1. Open `gemini.google.com` in Chrome
2. Open DevTools (F12) > Application > Cookies
3. Copy `__Secure-1PSID` and `__Secure-1PSIDTS` values
4. Paste when prompted

### NotebookLM Profile Not Working

**Symptoms:** Profile from NLM shows "not authenticated" in gemcli.

**Cause:** NLM profiles share Chrome sessions but gemcli needs its own Gemini cookies.

**Solution:**
```bash
gemcli login --profile <nlm-profile-name>
```

---

## Model-Specific Issues

### Pro/Thinking Model Returns Flash Responses

**Cause:** Without a BotGuard token, Google ignores the model header and returns Flash.

**Solution:** Token Factory must be operational:
1. Chrome must be installed and accessible
2. Run `gemcli doctor --verbose` to check Chrome status
3. Ensure all browser cookies are captured (not just 2)

### "ModelInvalid" Error (1050/1052)

**Cause:** Invalid model identifier.

**Valid models:**
- `gemini-3.0-flash` (or just `flash`)
- `gemini-3.0-pro` (or just `pro`)
- `gemini-3.0-flash-thinking` (or just `thinking`)

### Token Factory Error

**Symptoms:** `TokenFactoryError` when using Pro or Thinking models, or music generation.

**Checks:**
1. Is Chrome installed? `gemcli doctor --verbose`
2. Are all cookies captured? Check `~/.gemini-web-mcp-cli/profiles/<name>/auth.json`
3. Is the BotGuard token fresh? Tokens expire quickly
4. Running from a background process? Start persistent Chrome: `gemcli chrome start`

### Token Factory in Background Processes (LaunchAgent, cron, SSH)

**Symptoms:** `TokenFactoryError` when running from macOS LaunchAgent, cron job, systemd service, or SSH without display. Chrome cannot launch because background processes lack WindowServer/TCC access.

**Solution:** Start persistent Chrome from an interactive terminal:
```bash
gemcli chrome start              # Start headless daemon (survives terminal close)
gemcli chrome status             # Verify it's running and authenticated
```

Token Factory will automatically find the persistent Chrome on ports 9222-9231.

**After reboot:** Run `gemcli chrome start` again from an interactive terminal.

---

## Image/Video/Music Generation Issues

### Image Generation Fails / "No images generated"

**Common causes:**
- Chrome not running — image generation requires BotGuard + tool activation (`gemcli chrome start`)
- Content policy rejection (try different prompt)
- Auth cookies expired (`gemcli login`)

**Headless/background environments:** Image generation requires Chrome for BotGuard token capture. Ensure the persistent Chrome daemon is running: `gemcli chrome start`

### Music Generation Fails

**Common causes:**
- Chrome not running — music requires BotGuard even on Flash (`gemcli chrome start`)
- Content policy rejection (try different prompt or style)
- Auth cookies expired (`gemcli login`)
- Invalid style preset name (run `gemcli music --list-styles` for valid names)
- Running from background process — start persistent Chrome first

**Style preset tips:**
- Use exact preset names: `8-bit`, `k-pop`, `cinematic`, etc.
- Aliases also work: `chiptune` → `8-bit`, `kpop` → `k-pop`, `ambient` → `forest-bath`
- Case-insensitive: `K-Pop`, `k-pop`, `K-POP` all work

### Video Generation Produces Image Instead of Video

**Cause:** Video generation requires Chrome for BotGuard token + tool activation (tool_id=11). Without these, Gemini falls back to image generation.

**Solution:**
```bash
gemcli chrome start          # Ensure Chrome is running
gemcli limits                # Check video quota
gemcli video "prompt" -o out.mp4
```

### Video Generation Times Out

Videos via Veo 3.1 take 1-2 minutes to generate. If polling times out:
```bash
# Check status manually
gemcli video "prompt"  # Start generation
# Wait and check again
```

---

## MCP Server Issues

### "gemini-web-mcp binary not found"

**Solution:**
```bash
pip install gemini-web-mcp-cli[mcp]
# Or with uv:
uv pip install gemini-web-mcp-cli[mcp]
```

Then verify: `gemcli doctor`

### MCP Client Can't Connect

1. Check the server is configured: `gemcli setup list`
2. Add to your tool: `gemcli setup add <tool>`
3. Restart the AI tool after adding

### MCP Tool Returns Auth Error

The MCP server shares authentication with the CLI:
```bash
gemcli login           # Refresh auth
# Then restart the MCP-connected AI tool
```

---

## Network Issues

### IP Temporarily Blocked (Error 1060)

Google may temporarily block IPs making too many requests.

**Solutions:**
- Wait 5-10 minutes before retrying
- Use a VPN or different network
- Reduce request frequency

### Rate Limiting

Recommended delays between operations:
- Chat messages: 2 seconds
- Image generation: 5 seconds
- Video generation: 10 seconds (plus polling)
- Music generation: 5 seconds (plus polling)
- Research queries: 5 seconds

---

## Configuration Issues

### Config Directory Not Found

**Solution:** Run `gemcli login` to initialize the config directory at `~/.gemini-web-mcp-cli/`.

### Profile Doesn't Exist

```bash
gemcli profile list    # See available profiles
gemcli profile create <name>  # Create new one
```

### Wrong Active Profile

```bash
gemcli profile switch <name>
# Or use --profile flag for one-off:
gemcli chat "hello" --profile work
```

---

## Updating gemcli

### New Version Not Found After Release

**Symptoms:** `uv tool install --force gemini-web-mcp-cli` still installs the old version, or uv reports "no version found" for a specific release.

**Cause:** uv caches the PyPI package index locally. After a new release, the cached index may not include the new version yet — even if PyPI has it.

**Solution:**
```bash
uv cache clean && uv tool install --force --refresh gemini-web-mcp-cli
```

- `uv cache clean` — removes cached packages and index metadata
- `--refresh` — forces uv to re-fetch the package index from PyPI instead of using a cached copy

If you want to pin to a specific version:
```bash
uv cache clean && uv tool install --force --refresh 'gemini-web-mcp-cli==0.3.15'
```

After installing, verify:
```bash
gemcli --version
```

---

## Getting Help

```bash
gemcli --help              # All commands
gemcli <command> --help    # Specific command help
gemcli --ai                # AI-optimized full docs
gemcli doctor --verbose    # Detailed diagnostics
```

If issues persist, check the project repository for known issues.
