Tech Stack Advisor - Code Viewer

# Troubleshooting Guide

## Common Issues

### 1. Authentication Error: "invalid x-api-key"

**Error Message:**
```
Security agent error: Error code: 401 - {'type': 'error',
'error': {'type': 'authentication_error', 'message': 'invalid x-api-key'}}
```

**Cause:** Invalid or missing Anthropic API key

**Fix:**

1. **Get API Key:**
   - Visit: https://console.anthropic.com/
   - Sign up (free $5 credits)
   - Create API key in "API Keys" section
   - Copy key (starts with `sk-ant-`)

2. **Update `.env`:**
   ```bash
   cd /Users/admin/codeprojects/tech-stack-advisor
   nano .env
   ```

   Replace:
   ```
   ANTHROPIC_API_KEY=test-key
   ```

   With:
   ```
   ANTHROPIC_API_KEY=sk-ant-api03-your-real-key-here
   ```

3. **Restart API:**
   ```bash
   # Kill existing server
   lsof -ti :8000 | xargs kill -9

   # Restart
   python -m backend.src.api.main
   ```

4. **Verify:**
   ```bash
   # Check API key is set
   grep ANTHROPIC_API_KEY .env | grep -v "test-key"

   # Should show your real key (not test-key)
   ```

---

### 2. API Won't Start - Port Already in Use

**Error:**
```
Address already in use
```

**Fix:**
```bash
# Find and kill process on port 8000
lsof -ti :8000 | xargs kill -9

# Or use different port
uvicorn backend.src.api.main:app --port 8001
```

---

### 3. Can't Access Web UI

**Symptoms:**
- Cannot open http://localhost:8000
- Browser shows "Connection refused"

**Fix:**

1. **Check API is running:**
   ```bash
   curl http://localhost:8000/health
   ```

   Should return:
   ```json
   {"status":"healthy","version":"0.1.0","agents_loaded":4}
   ```

2. **Start API if not running:**
   ```bash
   cd /Users/admin/codeprojects/tech-stack-advisor
   source .venv/bin/activate
   python -m backend.src.api.main
   ```

   Or use the convenience script:
   ```bash
   ./run_app.sh
   ```

3. **Check port is available:**
   ```bash
   lsof -i :8000
   ```

   If another process is using port 8000, kill it or use a different port.

4. **Access the UI:**
   Open http://localhost:8000 in your browser

---

### 4. Rate Limited

**Error:**
```
429 - Rate limit exceeded: 5 per 1 hour
```

**This is expected behavior for demo mode!**

**Options:**

1. **Wait 1 hour** (demo limit: 5 queries/hour)

2. **Increase limit** (for development):
   Edit `.env`:
   ```bash
   RATE_LIMIT_DEMO=100/hour
   ```
   Restart API.

3. **Implement authentication** (future feature)

---

### 5. Daily Budget Exceeded

**Error:**
```
429 - Daily budget of $2.0 exceeded. Current cost: $2.15
```

**Fix:**

1. **Increase budget** (edit `.env`):
   ```bash
   DAILY_BUDGET_USD=10.00
   ```

2. **Wait until tomorrow** (resets at midnight)

3. **Check metrics:**
   ```bash
   curl http://localhost:8000/metrics
   ```

---

### 6. NumPy Compatibility Error

**Error:**
```
NumPy 1.x cannot be run in NumPy 2.x
```

**Fix:**
```bash
pip install "numpy<2"
```

---

### 7. Qdrant Connection Error

**Error:**
```
Connection refused to Qdrant
```

**For Testing - Use Local Mode:**
```bash
python scripts/ingest_knowledge.py --local
```

**For Production - Check Qdrant Config:**
```bash
# Verify credentials in .env
grep QDRANT .env

# Should have:
QDRANT_URL=https://xxxxx.qdrant.io
QDRANT_API_KEY=xxxxx
```

**Get Qdrant Cloud (Free):**
- Visit: https://cloud.qdrant.io/
- Sign up (1GB free)
- Create cluster
- Copy URL and API key to `.env`

---

### 8. Import Errors

**Error:**
```
ModuleNotFoundError: No module named 'xxx'
```

**Fix:**
```bash
cd /Users/admin/codeprojects/tech-stack-advisor
source .venv/bin/activate
pip install -e ".[dev]"
```

---

### 9. Slow Response Times

**Symptoms:**
- Queries take > 10 seconds
- Timeout errors

**Causes:**
1. **Cold start** - First query loads models (~3 seconds extra)
2. **LLM latency** - Claude API calls take 1-2 seconds each
3. **Network issues** - Check internet connection

**Expected Times:**
- First query: 5-6 seconds (model loading)
- Subsequent queries: 2-4 seconds (normal)

**If consistently slow:**
```bash
# Check API health
curl http://localhost:8000/metrics

# Look for "daily_tokens" - high usage = slower
```

---

### 10. Empty/Incomplete Results

**Symptoms:**
- Some agent tabs show "No recommendations available"
- Missing data in results

**Causes:**
1. **Agent error** - Check logs
2. **Parsing failed** - Query too short/vague
3. **API error** - LLM request failed

**Fix:**
1. **Try more detailed query:**
   ```
   Bad:  "database for app"
   Good: "I'm building a chat application for 100K daily users
          with real-time messaging, need database recommendations"
   ```

2. **Check API logs:**
   ```bash
   # Look for error messages in console where API is running
   ```

3. **Verify all agents loaded:**
   ```bash
   curl http://localhost:8000/health
   # Should show: "agents_loaded": 4
   ```

---

## Diagnostic Checklist

Run these commands to diagnose issues:

```bash
# 1. Check environment
cd /Users/admin/codeprojects/tech-stack-advisor
source .venv/bin/activate

# 2. Verify API key (should NOT be "test-key")
grep ANTHROPIC_API_KEY .env | grep -v "#"

# 3. Test API health
curl http://localhost:8000/health

# 4. Check metrics
curl http://localhost:8000/metrics

# 5. Test recommendation (should not error)
curl -X POST http://localhost:8000/recommend \
  -H "Content-Type: application/json" \
  -d '{"query":"Test query for chat app with 10K users"}'

# 6. Check ports
lsof -i :8000  # API
lsof -i :8501  # UI

# 7. Verify Python packages
pip list | grep -E "anthropic|langchain|qdrant|fastapi|streamlit"
```

---

## Getting Help

If none of these solutions work:

1. **Check logs** in the terminal where API/UI is running
2. **Review documentation** in project directory (8 guides)
3. **Test with minimal query** to isolate issue
4. **Try fresh install:**
   ```bash
   rm -rf .venv
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -e ".[dev]"
   ```

---

### 11. Authentication / Login Issues

**Symptoms:**
- Can't log in
- "Unauthorized" errors
- Google OAuth not working

**Fix:**

1. **For local login:**
   - Make sure you registered first at http://localhost:8000/register.html
   - Check email and password are correct
   - Password must be at least 8 characters

2. **For Google OAuth:**
   - Check Google OAuth is configured in `.env`:
     ```bash
     grep GOOGLE .env
     ```
   - Make sure `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are set
   - Verify redirect URI matches: `http://localhost:8000/auth/google/callback`
   - See `backend/static/GOOGLE_OAUTH_SETUP.md` for setup guide

3. **JWT Token Issues:**
   - Clear browser localStorage and login again
   - Token expires after 1 hour - re-login if expired
   - Check browser console for errors (F12 → Console tab)

4. **Admin Access:**
   - Only admin@example.com has admin role by default
   - Regular users cannot access `/admin.html`

---

## Quick Reference

**Start Everything:**
```bash
./run_app.sh
```

**Restart API:**
```bash
lsof -ti :8000 | xargs kill -9
python -m backend.src.api.main
```

**View Logs:**
```bash
# Check terminal where API is running
```

**Check Status:**
- Web UI: http://localhost:8000
- Login: http://localhost:8000/login.html
- Register: http://localhost:8000/register.html
- Admin: http://localhost:8000/admin.html
- API Health: http://localhost:8000/health
- API Metrics: http://localhost:8000/metrics
- API Docs: http://localhost:8000/docs