# Troubleshooting Guide

## Status: "Google account: not connected"

### Root Cause
Missing Google OAuth credentials file at `backend/data/credentials.json`

### Solution
Follow: [SETUP_GOOGLE_OAUTH.md](SETUP_GOOGLE_OAUTH.md)

**Quick recap:**
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create project → Enable APIs (Gmail, Calendar, Tasks)
3. Create OAuth consent screen
4. Create Desktop app OAuth credentials
5. Download JSON file
6. Save to: `backend/data/credentials.json`
7. Restart backend
8. Click "Connect Google account" in Settings

---

## Status: "Model: unavailable"

### Root Cause
Missing or incorrect LLM provider API key in `.env`

### Solution
Choose ONE option:

#### Option A: OpenAI (Recommended)
```bash
# 1. Get API key from: https://platform.openai.com/api-keys
# 2. Edit backend/.env
MODEL_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4o

# 3. Restart backend
# 4. Check Settings page - should show ✅ Model: available
```

#### Option B: Claude/Anthropic
```bash
# 1. Get API key from: https://console.anthropic.com/
# 2. Edit backend/.env
MODEL_PROVIDER=claude
ANTHROPIC_API_KEY=sk-ant-your-key-here
ANTHROPIC_MODEL=claude-haiku-4-5-20251001

# 3. Restart backend
```

#### Option C: Ollama (Free, Local)
```bash
# 1. Download Ollama from: https://ollama.ai
# 2. Install and run it
# 3. Pull a model: ollama pull qwen2.5:7b-instruct
# 4. Edit backend/.env
MODEL_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5:7b-instruct

# 5. Restart backend
```

See [SETUP_ENV.md](SETUP_ENV.md) for detailed instructions.

---

## Problem: "Morning Briefing shows empty priorities"

### Possible Causes

#### 1. No Google Integration
- Status page shows: ❌ Google account: not connected
- **Fix**: Connect Google account (see above)

#### 2. No LLM Model
- Status page shows: ❌ Model: unavailable
- **Fix**: Set up LLM provider (see above)

#### 3. Empty Email/Calendar
- You literally have no emails or calendar events
- **Fix**: Send yourself test emails or create calendar events

#### 4. Backend Error
- Check backend logs for errors:
  ```bash
  # In another terminal, watch the backend output
  python -m uvicorn app.main:app --reload --port 8000
  ```
- Look for ERROR or WARNING messages

---

## Problem: Frontend not loading

### Symptom
- Browser shows blank page
- Console shows 404 errors
- Can't access http://localhost:5173

### Solutions

#### 1. Frontend not running
```bash
# Terminal 1: Start frontend
cd frontend
npm run dev

# Should show: "Local: http://localhost:5173"
```

#### 2. Dependencies not installed
```bash
cd frontend
npm install
npm run dev
```

#### 3. Port 5173 already in use
```bash
# Find process using port 5173
lsof -i :5173  # Mac/Linux
netstat -ano | findstr :5173  # Windows

# Kill it or use different port
npm run dev -- --port 5174
```

#### 4. Clear cache
```bash
# Clear npm cache
npm cache clean --force

# Clear browser cache
# Chrome: Cmd+Shift+Delete (Mac) or Ctrl+Shift+Delete (Windows)
```

---

## Problem: Backend not responding

### Symptom
- Frontend shows "Error connecting to backend"
- API calls return 500 errors
- Cannot generate Morning Briefing

### Solutions

#### 1. Backend not running
```bash
# Terminal 1: Start backend
cd backend
python -m uvicorn app.main:app --reload --port 8000

# Should show: "Uvicorn running on http://127.0.0.1:8000"
```

#### 2. Port 8000 already in use
```bash
# Find process using port 8000
lsof -i :8000  # Mac/Linux
netstat -ano | findstr :8000  # Windows

# Kill it or use different port
python -m uvicorn app.main:app --port 8001
```

#### 3. Missing Python dependencies
```bash
cd backend
python -m pip install -r requirements.txt
python -m uvicorn app.main:app --reload --port 8000
```

#### 4. Check backend logs
```bash
# The terminal where you ran the backend will show logs
# Look for ERROR lines like:
# ERROR: Application startup failed
# ERROR: ModuleNotFoundError: No module named 'fastapi'
```

---

## Problem: "CORS error" or "blocked by CORS policy"

### Symptom
Browser console shows:
```
Access to XMLHttpRequest at 'http://localhost:8000/briefing' 
from origin 'http://localhost:5173' 
has been blocked by CORS policy
```

### Solution

#### Check frontend URL
- Frontend should be at: `http://localhost:5173`
- If at a different port, update `backend/.env`:
  ```
  FRONTEND_ORIGIN=http://localhost:5174
  ```
  Then restart backend

#### Check backend CORS config
- Verify `backend/.env` has:
  ```
  FRONTEND_ORIGIN=http://localhost:5173
  ```
- Restart backend after changing

#### Clear browser cache
- Chrome: Cmd+Shift+Delete (Mac) or Ctrl+Shift+Delete (Windows)
- Restart browser

---

## Problem: Google login hangs or fails

### Symptom
- Click "Connect Google account"
- Browser window opens
- Stays on Google login screen
- Never redirects back to app

### Causes & Solutions

#### 1. Wrong OAuth app type
- You created "Web app" instead of "Desktop app"
- **Fix**: Delete the credential, create a new "Desktop app"

#### 2. Credential file not in right place
- Should be: `backend/data/credentials.json`
- **Fix**: Move file to correct location, restart backend

#### 3. Google Cloud project issues
- OAuth consent screen not set up
- No test users added
- **Fix**: Follow [SETUP_GOOGLE_OAUTH.md](SETUP_GOOGLE_OAUTH.md) again

#### 4. Network/firewall issue
- Try in incognito window
- Try from a different network
- Check if localhost:5173 is accessible

---

## Problem: Approvals queue empty but things don't work

### Symptom
- Can compose an email but nothing happens
- Calendar doesn't update
- Tasks not created

### Causes

#### 1. No Google integration
- Needs: ✅ Google account connected
- **Fix**: Go to Settings, click "Connect Google account"

#### 2. Action requires approval but UI not showing it
- Backend generated approval but frontend not displaying
- **Fix**: Refresh page, check browser console for errors

#### 3. Backend error processing action
- Check backend logs for ERROR messages
- Look for: "Failed to send email" or similar

---

## Checking System Status

### Backend Health
```bash
curl http://localhost:8000/
# Should return: {"service": "personal-chief-of-staff", "status": "ok"}
```

### Frontend Health
```bash
# Just open in browser: http://localhost:5173/settings
# Should load and show connection status
```

### Check All Logs
```bash
# Backend logs show in terminal where you ran uvicorn
# Frontend logs show in browser DevTools:
# - Open: http://localhost:5173
# - Press: F12
# - Click: Console tab
# - Look for red ERROR messages
```

---

## Getting Help

1. **Check logs first**
   - Backend: Terminal output
   - Frontend: Browser DevTools (F12)

2. **Try these files**
   - [SETUP_GOOGLE_OAUTH.md](SETUP_GOOGLE_OAUTH.md) - Google setup
   - [SETUP_ENV.md](SETUP_ENV.md) - LLM provider setup
   - [README.md](README.md) - Full documentation

3. **Common steps that fix most issues**
   - Restart both backend and frontend
   - Clear browser cache
   - Check .env file has proper values
   - Verify backend/data/ folder exists and has credentials.json

---

## Checklist for Full Setup

- [ ] Backend running on port 8000
- [ ] Frontend running on port 5173
- [ ] `backend/.env` created with LLM provider configured
- [ ] `backend/data/credentials.json` exists (Google OAuth)
- [ ] Settings page shows: ✅ Model: available
- [ ] Settings page shows: ✅ Google account: connected
- [ ] Can generate Morning Briefing without errors
- [ ] Can ask a question in Chat page
- [ ] Can compose and approve an email

If all checkboxes are done, the app is fully set up! 🎉