Troubleshooting Guide

This guide helps you resolve common issues with the Multi-Agent Framework.

Table of Contents

• Installation Issues
• API Key Problems
• Agent Issues
• Task Execution Problems
• Performance Issues
• Integration Problems
• Error Messages
• Debugging Tools
• Getting Help

Installation Issues

Python Version Errors

Problem: Python version 3.7 is not supported

Solution:

# Check Python version
python --version

# Install Python 3.10+ using pyenv
curl https://pyenv.run | bash
pyenv install 3.11.7
pyenv global 3.11.7

# Or use system package manager
# Ubuntu/Debian
sudo apt update && sudo apt install python3.11

# macOS
brew install [email protected]

Import Errors

Problem: ModuleNotFoundError: No module named 'multi_agent_framework'

Solutions:

1. Activate virtual environment:

source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

2. Reinstall package:

pip install -e .

3. Check Python path:

import sys
print(sys.path)
# Ensure project directory is in path

Permission Denied

Problem: Permission denied when creating directories

Solutions:

# Fix directory permissions
chmod -R u+w .maf/message_queues .maf_logs

# Run with proper user
sudo chown -R $USER:$USER .

# Use different directory
maf init --config-dir ~/maf-config

API Key Problems

No API Keys Found

Problem: Error: No API keys configured

Solutions:

1. Check .env file exists:

ls -la .env
# If missing, create from template
cp .env.example .env

2. Verify key format:

# Correct format (no quotes)
GEMINI_API_KEY=AIzaSyDCvp5MTJLUdtaYrQDgddddexample

# Wrong formats
GEMINI_API_KEY="AIzaSyDCvp5MTJLUdtaYrQDgddddexample"  # No quotes
GEMINI_API_KEY= AIzaSyDCvp5MTJLUdtaYrQDgddddexample   # No spaces

3. Load environment manually:

export $(cat .env | xargs)

Invalid API Key

Problem: 401 Unauthorized: Invalid API key

Solutions:

1. Verify key is correct:

# Test Gemini key
import google.generativeai as genai
genai.configure(api_key="your_key")
model = genai.GenerativeModel('gemini-pro')
response = model.generate_content("Hello")
print(response.text)

2. Check key permissions:

• Gemini: Enable API in Google Cloud Console
• Claude: Verify tier and rate limits
• OpenAI: Check organization and billing

3. Try different provider:

{
  "agent_config": {
    "default_model_provider": "anthropic"  // Switch provider
  }
}

Rate Limiting

Problem: 429 Too Many Requests

Solutions:

1. Add delays:

{
  "performance": {
    "rate_limit_per_minute": 30,
    "request_delay": 2
  }
}

2. Use multiple API keys:

GEMINI_API_KEY_1=key1
GEMINI_API_KEY_2=key2
# Framework will rotate keys

Agent Issues

Agents Not Starting

Problem: Agent failed to start: frontend_agent

Solutions:

1. Check logs:

maf logs frontend_agent --tail 100

2. Verify dependencies:

# Check if agent is enabled
maf config get agent_config.enabled_agents

# Enable agent
maf config set agent_config.enabled_agents '["orchestrator","frontend_agent"]'

3. Start individually:

# Start only problematic agent
maf launch --agents orchestrator,frontend_agent --verbose

Agent Timeout

Problem: Agent orchestrator timed out

Solutions:

1. Increase timeout:

{
  "performance": {
    "task_timeout": 600,  // 10 minutes
    "agent_startup_timeout": 60
  }
}

2. Check system resources:

# Memory usage
free -h

# CPU usage
top

# Disk space
df -h

Agent Communication Failures

Problem: Failed to publish event: Connection refused

Solutions:

1. Check event bus:

# If using Kafka
docker ps | grep kafka
docker-compose up -d kafka

# Switch to in-memory
maf config set event_bus.type "in_memory"

2. Clear message queue:

rm -rf .maf/message_queues/*
maf reset

Event-Driven Mode Not Processing Messages

Problem: Agents in event-driven mode not processing tasks

Solutions:

1. Update to latest version (includes inbox processing fix):

git pull origin main
pip install -e . --upgrade

2. Use polling mode as temporary workaround:

maf launch --mode polling

3. Check message inbox:

# See if messages are queued
ls -la .maf/message_queues/*_inbox.json

# Clear stale messages
rm -rf .maf/message_queues/*_inbox.json

Note: This issue was fixed in version 0.1.1 where agents now process inbox messages on startup.

Task Execution Problems

Tasks Stuck in Pending

Problem: Tasks remain in pending state

Solutions:

1. Check orchestrator:

maf logs orchestrator --follow

2. Manually assign:

# Restart with force assignment
maf reset
maf launch
maf trigger "Simple test task" --agents backend_agent

3. Debug task state:

import json
with open('.maf/state.json') as f:
    state = json.load(f)
    print(json.dumps(state['active_tasks'], indent=2))

Task Failures

Problem: Task failed: Error generating code

Solutions:

1. Check error details:

maf status --detailed
maf logs --level ERROR

2. Retry with simpler prompt:

# Break down complex task
maf trigger "Create user model" --wait
maf trigger "Add email field to user model" --wait

3. Use different model:

{
  "agent_models": {
    "backend_agent": {
      "provider": "openai",
      "name": "gpt-4-turbo-preview"
    }
  }
}

Code Integration Conflicts

Problem: Integration failed: Merge conflict

Solutions:

1. Manual resolution:

# Find conflicting files
find . -name "*.conflict"

# Review changes
git diff

# Reset and retry
maf reset --hard

2. Disable smart integration:

{
  "integration": {
    "smart_merge": false,
    "validate_imports": false
  }
}

Performance Issues

Slow Response Times

Solutions:

1. Enable caching:

{
  "performance": {
    "cache_enabled": true,
    "cache_ttl": 7200
  }
}

2. Reduce parallel agents:

{
  "performance": {
    "parallel_agents": 2  // Reduce from default
  }
}

3. Use faster models:

{
  "agent_models": {
    "frontend_agent": {
      "provider": "gemini",
      "name": "gemini-2.0-flash-exp"  // Faster model
    }
  }
}

High Memory Usage

Solutions:

1. Set memory limits:

{
  "resource_limits": {
    "max_memory_mb": 1024,
    "gc_interval": 300
  }
}

2. Clear old data:

# Remove old logs
find .maf_logs -type f -mtime +7 -delete

# Clean message queue
rm -rf .maf/message_queues/*

Integration Problems

Project Type Not Detected

Problem: Failed to detect project type

Solutions:

1. Specify manually:

maf init --type nextjs

2. Add detection hints:

{
  "project_type": "nextjs",
  "technology_stack": {
    "frontend": ["next", "react", "typescript"]
  }
}

Git Integration Issues

Problem: Failed to commit changes

Solutions:

1. Check Git configuration:

git config user.email
git config user.name

# Set if missing
git config user.email "[email protected]"
git config user.name "Your Name"

2. Disable auto-commit:

{
  "integrations": {
    "git": {
      "auto_commit": false
    }
  }
}

Error Messages

Common Errors and Solutions

Error	Cause	Solution
Connection timeout	Network issues	Check internet, firewall, proxy
Invalid JSON	Config syntax error	Validate with jq .maf-config.json
Agent not found	Typo in agent name	Check maf config get agent_config.enabled_agents
Insufficient quota	API limits	Upgrade plan or switch provider
File not found	Wrong project directory	Run maf init in correct directory

Decoding Stack Traces

# Example error
Traceback (most recent call last):
  File "agents/base_agent.py", line 45, in process_task
    result = await self.generate_code(task)
KeyError: 'model_name'

# Solution: Check agent configuration
maf config get agent_config.agent_models.frontend_agent

Debugging Tools

Enable Debug Mode

# Run with debug logging
MAF_LOG_LEVEL=DEBUG maf launch

# Or in config
{
  "logging": {
    "level": "DEBUG",
    "verbose": true
  }
}

Health Check Script

#!/usr/bin/env python3
# health_check.py
import os
import json
import sys

def check_health():
    checks = {
        "env_file": os.path.exists(".env"),
        "config_file": os.path.exists(".maf-config.json"),
        "api_keys": any(os.getenv(k) for k in 
                       ["GEMINI_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"]),
        "directories": all(os.path.exists(d) for d in 
                          [".maf/message_queues", ".maf_logs"])
    }
    
    for check, passed in checks.items():
        status = "✓" if passed else "✗"
        print(f"{status} {check}")
    
    if not all(checks.values()):
        sys.exit(1)

if __name__ == "__main__":
    check_health()

Monitor Resources

# Create monitoring script
cat > monitor.sh << 'EOF'
#!/bin/bash
while true; do
    clear
    echo "=== MAF Resource Monitor ==="
    echo "Memory: $(free -h | grep Mem | awk '{print $3"/"$2}')"
    echo "CPU: $(top -bn1 | grep "Cpu(s)" | awk '{print $2"%"}')"
    echo "Agents: $(ps aux | grep -c "[m]af.*agent")"
    echo "Messages: $(find .maf/message_queues -type f | wc -l)"
    sleep 5
done
EOF
chmod +x monitor.sh

Getting Help

Before Asking for Help

1. Check logs thoroughly:

maf logs --level ERROR --tail 200 > error_logs.txt

2. Gather system info:

maf status --detailed --json > system_info.json
python --version
pip list | grep multi-agent

3. Try minimal example:

# Create test directory
mkdir maf-test && cd maf-test
maf init --minimal
maf launch --agents orchestrator,backend_agent
maf trigger "Create hello world function"

Where to Get Help

1. GitHub Issues: Report bugs

   • Include error logs
   • System information
   • Steps to reproduce

2. Discussions: Ask questions

   • General usage questions
   • Best practices
   • Feature requests

3. Documentation:

   • Installation Guide
   • Configuration Guide
   • Architecture Overview

Creating Good Bug Reports

## Bug Description
Brief description of the issue

## Environment
- OS: macOS 13.0
- Python: 3.11.7
- MAF Version: 0.1.0
- LLM Provider: Gemini

## Steps to Reproduce
1. Run `maf init`
2. Configure with...
3. Execute command...

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Error Logs

Paste relevant logs here

## Additional Context
Any other relevant information

Quick Fixes

Reset Everything

# Complete reset
maf stop --force
rm -rf .maf_*
rm .env
maf init --force

Switch Providers

# Quick provider switch
export MAF_DEFAULT_PROVIDER=anthropic
export MAF_DEFAULT_MODEL=claude-3-sonnet-20240229
maf launch

Emergency Recovery

# Backup current state
tar -czf maf-backup.tar.gz .maf_* .env .maf-config.json

# Recovery mode
python -m multi_agent_framework.recovery_tool recover

# Restore from backup
tar -xzf maf-backup.tar.gz

Next Steps

• Review Best Practices
• Learn about Performance Tuning
• Explore Advanced Features
• Join the Community