troubleshooting

AutoGPT Troubleshooting Guide

Installation Issues

Docker compose fails

**Error**: `Cannot connect to the Docker daemon`

**Fix**:

# Start Docker daemon
sudo systemctl start docker

# Or on macOS
open -a Docker

# Verify Docker is running
docker ps

**Error**: `Port already in use`

**Fix**:

# Find process using port
lsof -i :8006

# Kill process
kill -9 <PID>

# Or change port in docker-compose.yml

Database migration fails

**Error**: `Migration failed: relation already exists`

**Fix**:

# Reset database
docker compose down -v
docker compose up -d db

# Re-run migrations
cd backend
poetry run prisma migrate reset --force
poetry run prisma migrate deploy

**Error**: `Connection refused to database`

**Fix**:

# Check database is running
docker compose ps db

# Check database logs
docker compose logs db

# Verify DATABASE_URL in .env
echo $DATABASE_URL

Frontend build fails

**Error**: `Module not found: Can't resolve '@/components/...'`

**Fix**:

# Clear node modules and reinstall
rm -rf node_modules
rm -rf .next
npm install

# Or with pnpm
pnpm install --force

**Error**: `Supabase client not initialized`

**Fix**:

# Verify environment variables
cat .env | grep SUPABASE

# Required variables:
# NEXT_PUBLIC_SUPABASE_URL=http://localhost:8000
# NEXT_PUBLIC_SUPABASE_ANON_KEY=your-key

Service Issues

Backend services not starting

**Error**: `rest_server exited with code 1`

**Diagnose**:

# Check logs
docker compose logs rest_server

# Common issues:
# - Missing environment variables
# - Database connection failed
# - Redis connection failed

**Fix**:

# Verify all dependencies are running
docker compose ps

# Restart services in order
docker compose restart db redis rabbitmq
sleep 10
docker compose restart rest_server executor

Executor not processing tasks

**Error**: Tasks stuck in QUEUED status

**Diagnose**:

# Check executor logs
docker compose logs executor

# Check RabbitMQ queue
# Visit http://localhost:15672 (guest/guest)
# Look at queue depths

**Fix**:

# Restart executor
docker compose restart executor

# If queue is backlogged, scale executors
docker compose up -d --scale executor=3

WebSocket connection fails

**Error**: `WebSocket connection to 'ws://localhost:8001/ws' failed`

**Fix**:

# Check WebSocket server is running
docker compose logs websocket_server

# Verify port is accessible
nc -zv localhost 8001

# Check firewall rules
sudo ufw allow 8001

Agent Execution Issues

Agent stuck in running state

**Diagnose**:

# Check execution status via API
curl http://localhost:8006/api/v1/executions/{execution_id}

# Check node execution logs
docker compose logs executor | grep {execution_id}

**Fix**:

# Cancel stuck execution via API
import requests

response = requests.post(
    f"http://localhost:8006/api/v1/executions/{execution_id}/cancel",
    headers={"Authorization": f"Bearer {token}"}
)

LLM block timeout

**Error**: `TimeoutError: LLM call exceeded timeout`

**Fix**:

# Increase timeout in block configuration
{
    "block_id": "llm-block",
    "config": {
        "timeout_seconds": 120,  # Increase from default 60
        "max_retries": 3
    }
}

Credential errors

**Error**: `CredentialsNotFoundError: No credentials for provider openai`

**Fix**: 1. Navigate to Profile > Integrations 2. Add OpenAI API key 3. Ensure graph has credential mapping

{
    "credential_mapping": {
        "openai": "user_credential_id"
    }
}

Memory issues during execution

**Error**: `MemoryError` or container killed (OOMKilled)

**Fix**:

# Increase memory limits in docker-compose.yml
executor:
    deploy:
        resources:
            limits:
                memory: 4G
            reservations:
                memory: 2G

Graph/Block Issues

Block not appearing in UI

**Diagnose**:

# Check block registration
from backend.data.block import get_all_blocks

blocks = get_all_blocks()
print([b.name for b in blocks])

**Fix**:

# Ensure block is imported in __init__.py
# backend/blocks/__init__.py
from backend.blocks.my_block import MyBlock

BLOCKS = [
    MyBlock,
    # ...
]

Graph save fails

**Error**: `GraphValidationError: Invalid link configuration`

**Diagnose**:

# Validate graph structure
from backend.data.graph import validate_graph

errors = validate_graph(graph_data)
print(errors)

**Fix**:

• Ensure all links connect valid nodes
• Check input/output name matches
• Verify required inputs are connected

Circular dependency detected

**Error**: `GraphValidationError: Circular dependency in graph`

**Fix**:

# Find cycle
import networkx as nx

G = nx.DiGraph()
for link in graph.links:
    G.add_edge(link.source_id, link.sink_id)

cycles = list(nx.simple_cycles(G))
print(f"Cycles found: {cycles}")

Performance Issues

Slow graph execution

**Diagnose**:

# Profile execution
import cProfile

profiler = cProfile.Profile()
profiler.enable()
await executor.execute_graph(graph_id, inputs)
profiler.disable()
profiler.print_stats(sort='cumulative')

**Fix**:

• Parallelize independent nodes
• Reduce unnecessary API calls
• Cache repeated computations

High database query latency

**Diagnose**:

# Enable query logging in PostgreSQL
docker exec -it autogpt-db psql -U postgres
\x
SHOW log_min_duration_statement;
SET log_min_duration_statement = 100;  -- Log queries > 100ms

**Fix**:

-- Add missing indexes
CREATE INDEX CONCURRENTLY idx_executions_user_created
ON "AgentGraphExecution" ("userId", "createdAt" DESC);

ANALYZE "AgentGraphExecution";

Redis memory growing

**Diagnose**:

# Check Redis memory usage
docker exec -it autogpt-redis redis-cli INFO memory

# Check key count
docker exec -it autogpt-redis redis-cli DBSIZE

**