minions-ai-agents/docs/TROUBLESHOOTING.md

🔥 Troubleshooting Guide

Common issues and solutions for the Antigravity Brain system.

---

🚨 API Errors

Error: 429 RESOURCE_EXHAUSTED (Quota Exceeded)

Symptoms:

• Agents stuck in retry loop
• "You exceeded your current quota" in logs

Causes:

• API rate limit hit (especially with Gemini 2.0-flash-exp: only 10 RPM!)
• Memory tools calling API too fast

Solutions:

1. Switch to higher-quota model:

   LLM_MODEL_FAST=gemini-2.5-flash-lite-preview-06-17  # 4000 RPM
   

2. Wait for quota reset (typically 1 minute)

3. Check current quota:

   • Gemini: https://console.cloud.google.com/apis/api/generativelanguage.googleapis.com/quotas
   • OpenAI: https://platform.openai.com/usage

---

Error: OPENAI_API_KEY must be set

Symptoms:

• Memory tools fail with "api_key client option must be set"

Cause:

• Mem0's LLM configuration missing

Solution:

• Ensure src/config.py has LLM config in get_mem0_config()
• Check that LLM_PROVIDER in .env matches a supported provider

---

Error: Template variable 'X' not found

Symptoms:

• Agent crashes when loading knowledge

Cause:

• {variable} syntax in markdown files interpreted as CrewAI template

Solution:

• Escape braces in code examples: use PATH_VAR instead of {path}
• Check src/knowledge/standards/*.md for unescaped {}

---

🐳 Docker Issues

Container keeps restarting

Check logs:

docker logs antigravity_brain --tail 100

Common causes:

• Missing .env file
• Invalid API key
• Python import errors

---

Qdrant connection refused

Symptoms:

• "Connection refused" to port 6333

Solutions:

1. Check Qdrant is running:

   docker ps | findstr qdrant
   

2. Check host configuration:

   QDRANT_HOST=qdrant  # Docker service name, NOT localhost
   

3. Restart Qdrant:

   docker-compose restart qdrant
   

---

Changes not reflected

Problem: Code changes don't appear after saving

Solution:

docker-compose restart app

Or for full rebuild:

docker-compose build --no-cache app
docker-compose up -d

---

🤖 Agent Issues

Agent not found

Error: No persona found matching 'agent-name'

Solutions:

1. Check filename matches:

   src/agents/personas/persona-<exact-name>.md
   

2. Use correct search pattern:

   # This searches for *agent-name* in filename
   AgentFactory.create_agent("agent-name")
   

---

Agent loads but doesn't respond

Possible causes:

1. LLM API error - Check logs for 429/401
2. Empty backstory - Ensure persona has content
3. Tool errors - Check if tools are raising exceptions

Debug:

docker logs antigravity_brain 2>&1 | findstr "Error ERROR Exception"

---

Agent using wrong model

Check: Ensure model_tier is set correctly:

agent = AgentFactory.create_agent("name", model_tier="smart")  # Uses LLM_MODEL_SMART
agent = AgentFactory.create_agent("name", model_tier="fast")   # Uses LLM_MODEL_FAST

---

🧠 Memory Issues

Memory not saving

Check Qdrant dashboard:

http://localhost:6333/dashboard

Verify collection exists: Should see itguys_antigravity_v1 (or your MEMORY_PROJECT_ID)

---

Memory search returns nothing

Possible causes:

1. Embedding mismatch - Don't change MEMORY_EMBEDDING_PROVIDER after data exists
2. Wrong project ID - Check MEMORY_PROJECT_ID matches
3. Qdrant empty - No memories saved yet

---

🌐 Web UI Issues

Chainlit not loading

Check port:

netstat -an | findstr 8000

Check container:

docker logs antigravity_brain | findstr -i "error"

---

"Could not reach server" toast

Cause: Usually LLM API timeout or error

Solution: Check API key and quota

---

📋 Quick Diagnostic Commands

# Check all containers
docker ps

# View real-time logs
docker logs antigravity_brain -f

# Check for errors only
docker logs antigravity_brain 2>&1 | findstr "ERROR Error error Exception"

# Restart everything
docker-compose down && docker-compose up -d

# Full rebuild
docker-compose build --no-cache && docker-compose up -d

# Check Qdrant health
curl http://localhost:6333/health

# Test Gemini API
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite-preview-06-17:generateContent?key=YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Hello"}]}]}'

---

🆘 Getting Help

1. Check logs first - 90% of issues are in Docker logs
2. Verify .env - Most config issues are environment variables
3. Test API separately - Ensure your API key works outside the app
4. Check quotas - Rate limits are the #1 cause of failures