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:

# 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".