# Troubleshooting

## Common Issues

### Server Not Found at Startup

**Symptom:** No models appear, or you see a warning about server initialization.

**Cause:** The server didn't respond within the 5-second health check timeout.

**Solution:**
1. Verify the server is running: `curl http://127.0.0.1:8080/health`
2. Run `/models` to retry without timeout
3. Check your URL configuration in `.pi/settings.json`

### Models Show ⛔ Unauthorized

**Symptom:** All models display the unauthorized icon.

**Cause:** The server requires API key authentication, but no key is configured.

**Solution:**
1. Run `/login` and select "Use an API key"
2. Enter your API key when prompted
3. Alternatively, add the key to `~/.pi/agent/auth.json`

### Model Fails to Load

**Symptom:** Model status shows 🔴 Failed after load attempt.

**Possible causes and solutions:**

| Cause | Solution |
|-------|----------|
| Model file doesn't exist | Verify the model path on the server |
| Insufficient memory | Try a smaller model or free up RAM |
| Wrong API key | Run `/login` to re-authenticate |
| Server is busy | Wait and retry, or check server logs |
| Model already loaded | Use "Switch" instead of "Load" |

### Slow Loading

**Symptom:** Loading takes a long time or times out.

**Solutions:**
1. Check server logs for loading progress
2. Verify the model file is on a fast storage device (SSD/NVMe)
3. Try loading a smaller model
4. Note: The 60-second timeout applies to progress detection, not actual loading

### SSE Not Working

**Symptom:** No real-time progress updates during loading.

**Cause:** SSE is not supported by the server or is blocked by a proxy/firewall.

**Solution:** The extension automatically falls back to polling. No action needed.

> **Note:** LiteLLM proxies never support SSE — polling is always used.

### Multiple Servers — Only One Shows Models

**Symptom:** You configured multiple servers but only one displays models.

**Cause:** The unreachable servers are filtered out at startup.

**Solution:** Run `/models` to retry all servers without the startup timeout.

### Config Not Taking Effect

**Symptom:** Changes to `.pi/settings.json` don't take effect.

**Solution:**
1. Ensure the file is valid JSON
2. Restart Pi to reload configuration
3. Check priority order — project config overrides global settings

### Thinking Budgets Not Applied

**Symptom:** Custom thinking budgets don't seem to work.

**Solution:**
1. Verify the budgets are in the correct settings file
2. Only `minimal`, `low`, `medium`, and `high` are configurable
3. `off`, `xhigh`, and `max` are fixed and cannot be overridden

## Debugging

### Enable Verbose Logging

Check Pi's logs for extension errors:

```bash
# Check Pi logs
cat ~/.pi/agent/logs/*.log | grep -i "llama"
```

### Verify Server Health

Test your server directly:

```bash
# Health check
curl http://127.0.0.1:8080/health

# List models
curl http://127.0.0.1:8080/v1/models

# Get model props
curl http://127.0.0.1:8080/props?model=your-model.gguf&autoload=false
```

### Check Configuration

Verify your settings are loaded correctly:

```bash
# Check project settings
cat .pi/settings.json

# Check global settings
cat ~/.pi/agent/settings.json

# Check auth configuration
cat ~/.pi/agent/auth.json
```

## Getting Help

If you're still stuck:

1. Check the [GitHub Issues](https://github.com/faks/pi-gateway/issues) for similar problems
2. Include your configuration (redact API keys) and server logs when asking for help
3. Mention your Pi version and extension version