Troubleshooting

First Diagnostic Pass

docker compose ps
docker compose logs -f

bun health

Docker Services Won't Start

Symptoms: docker compose up -d fails or containers exit quickly.

docker system df
lsof -i :5432
lsof -i :6379
lsof -i :3000

Reset (destructive to local volumes and data):

docker compose down -v
docker compose up -d

Database Connection Refused

Symptoms: ECONNREFUSED, migration, or app startup failures.

docker compose ps postgres
docker compose logs postgres
docker compose exec postgres pg_isready -U postgres

Validate DATABASE_URL format in env (local default is postgresql://postgres:password@localhost:5432/ai).

Missing BETTER_AUTH_SECRET

If startup reports auth secret errors:

openssl rand -base64 32

Set the generated value in app/admin env files and restart dev processes.

MinIO Bucket Not Found

docker compose restart createbuckets

Manual bucket creation fallback:

docker compose exec minio mc alias set local http://localhost:9000 minioadmin minioadmin
docker compose exec minio mc mb local/ai-files --ignore-existing

Migrations Fail

bun health
bun db:studio

Dev-only destructive fallback:

bun db:push

Worker Not Processing Jobs

bun dev:worker
docker compose exec redis redis-cli ping
docker compose exec redis redis-cli

Then inside redis-cli:

KEYS bull:*

Telegram Bot Doesn't Respond (Optional)

Verify env vars:

• APP_URL
• TELEGRAM_CHAT_BOT_TOKEN
• TELEGRAM_CHAT_BOT_USERNAME
• TELEGRAM_CHAT_WEBHOOK_SECRET_TOKEN

Check webhook status:

curl "https://api.telegram.org/bot$TELEGRAM_CHAT_BOT_TOKEN/getWebhookInfo"

Then review app logs and ensure migrations are up-to-date.

Performance / Resource Issues

• Run fewer apps: bun dev:app instead of bun dev.
• Increase Docker Desktop resources.
• Stop optional heavy services when unused.
• Prune stale Docker artifacts if disk pressure is high.