Troubleshooting

Check service status

cd deploy
docker compose -f docker-compose.ee.yml ps

Services should show Up (healthy). A service showing Restarting has a startup failure.

View logs

# All services
make ee-logs

# Specific service
docker compose -f docker-compose.ee.yml logs -f server
docker compose -f docker-compose.ee.yml logs -f client
docker compose -f docker-compose.ee.yml logs -f postgres
docker compose -f docker-compose.ee.yml logs -f clickhouse

Common issues

Server won't start

Run docker compose -f docker-compose.ee.yml logs server and look for the error message.

Error in logs	Cause	Fix
SECRET_KEY is required	SECRET_KEY not set	Set SECRET_KEY in deploy/.env
Invalid ENCRYPTION_KEY	Key is not a valid Fernet key	Regenerate with python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
could not connect to server	PostgreSQL not ready	Wait 30s and check docker compose logs postgres
Migration failure	DB credentials mismatch	Ensure POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB match between server and postgres service

Client shows blank page or 502

docker compose -f docker-compose.ee.yml logs client

Common causes:

• Server is not yet healthy — wait for aiser-server-ee to show Up (healthy)
• NEXT_PUBLIC_API_URL points to wrong server address — rebuild after fixing: make ee-recreate

AI features not working

docker compose -f docker-compose.ee.yml logs server | grep -i "azure\|openai"

Error	Fix
AuthenticationError	Check AZURE_OPENAI_API_KEY
DeploymentNotFound	Check AZURE_OPENAI_DEPLOYMENT_NAME matches your Azure deployment
ResourceNotFound	Check AZURE_OPENAI_ENDPOINT — must end with /

ClickHouse remains unhealthy

ClickHouse takes 30–60 seconds on first start. Wait and re-run docker compose ps.

If still unhealthy:

docker compose -f docker-compose.ee.yml logs clickhouse

License key invalid

Verify LICENSE_KEY in deploy/.env matches the key from your purchase at aicser.com.

Health endpoints

curl http://localhost:8001/health   # Server
curl http://localhost:8123/ping     # ClickHouse

Reset and start fresh

cd deploy
make ee-reset  # WARNING: deletes all volumes and data
make ee