Skip to main content

AgentArea Troubleshooting Guide

🚨 Quick Diagnostics

Health Check Commands

Service Status Overview

🔧 Common Issues

1. Services Won’t Start

Symptoms

  • docker compose up fails
  • Services exit immediately
  • Port binding errors

Diagnosis

Solutions

Port Conflicts:
Docker Issues:
Permission Issues:

2. Database Connection Errors

Symptoms

  • “Connection refused” errors
  • Migration failures
  • App can’t connect to database

Diagnosis

Solutions

Database Not Ready:
Connection String Issues:
Reset Database:

3. Migration Issues

Symptoms

  • Alembic migration errors
  • “Revision not found” errors
  • Database schema mismatches

Diagnosis

Solutions

Run Migrations:
Reset Migration State:

4. Module Import Errors

Symptoms

  • ModuleNotFoundError
  • Import path issues
  • Python package not found

Diagnosis

Solutions

Rebuild Containers:
Install Dependencies: