doc/TROUBLESHOOTING.md

# 🔧 Troubleshooting Guide

This guide addresses common issues when running LifeFlow AI locally, particularly regarding API integrations and Docker environments.

## 🔴 Common Errors & Solutions

### 1. JSON Parsing Errors (Scout Agent)
**Symptom:** `❌ Error: Invalid JSON format.`
**Cause:** The LLM (especially smaller models like Flash-Lite) may output markdown backticks or Python-style booleans (`True` instead of `true`) in the JSON.
**Solution:**
* LifeFlow includes a `_robust_parse_json` method in `scout_toolkit.py` that attempts to auto-repair malformed JSON.
* If this persists, verify that your prompt explicitly requests "Raw JSON, no markdown".

### 2. Google Maps API: `REQUEST_DENIED` or `OVER_QUERY_LIMIT`
**Symptom:** Agent loop fails, or Map is empty.
**Check:**
* Ensure the following APIs are enabled in your Google Cloud Console:
    * **Places API (New)**
    * **Routes API**
    * **Maps JavaScript API** (for UI)
* **Billing:** You must have a billing account linked, even for the free tier.

### 3. MCP Connection Failed / Port Conflicts
**Symptom:** `❌ [System] MCP Connection Failed` in the console log.
**Cause:** The application attempts to spawn multiple subprocesses for `mcp_server_lifeflow.py`. If a previous run didn't close properly, ports/files might be locked.
**Solution:**
* Manually kill python processes: `pkill -f mcp_server_lifeflow.py`
* Restart the application.

### 4. "Ref ID Not Found" Loop
**Symptom:** The Leader Agent keeps asking the Scout to search again because it "cannot find the data".
**Cause:** The `poi_repo` (SQLite/File) might be persisting data from an old session, or the `session_id` mismatch.
**Solution:**
* Delete the `tmp/` directory or the database file to clear the cache.
* The system includes an auto-correction mechanism (visible in `weather_toolkit.py`) that tries to fetch the *latest* ID if the specific one is missing. Check the logs for `🔄 Auto-Correcting`.

## ⚙️ Environment Variables (`.env`)

Make sure your `.env` file matches this structure exactly:

```ini
# Core LLM
GOOGLE_API_KEY=AIzaSy...

# Tools
GOOGLE_MAPS_API_KEY=AIzaSy...  # Must have Places & Routes enabled
OPENWEATHER_API_KEY=abc123...

# Optional (for Fast Mode)
GROQ_API_KEY=gsk_...
```

## 🐛 Debugging Mode
To see the raw "Hot Potato" data flow:
1. Open core_team.py.
   - Set debug_mode=True in creat_team.
2. Open config.py
   - Set LOG_LEVEL="DEBUG".