Troubleshooting & FAQs

In this page

Symptoms, causes, and fixes for the errors most commonly hit when self-hosting. Grouped by where they show up: startup, network, PeerDB, Temporal, and post-upgrade.

Start here

docker compose ps                    # what's running / what's restarting
docker compose logs -f backend       # most informative starting point
docker compose exec backend bash     # shell in, swap "backend" for any service

---

Startup errors

Cannot connect to the Docker daemon

Docker isn’t running. Start Docker Desktop (Mac/Windows) or sudo systemctl start docker (Linux).

---

First boot takes 15+ min or looks stuck

Normal. First boot pulls every image from Docker Hub, a few GB in total, and nothing is built locally so there’s no compile step to hang on. Watch the pull actually progressing:

docker compose logs -f
docker compose pull        # re-run to resume an interrupted pull

---

ERROR: not enough free space

Docker Desktop’s virtual disk is full. Settings → Resources → Disk image size → raise to 100 GB+. Or reclaim space from unused images: docker system prune -af

---

Port already in use

lsof -i :3000                # swap 3000 for whichever port the error named
# then override it in .env:
FRONTEND_PORT=3100
BACKEND_PORT=8100
docker compose up -d         # recreate so the new binding takes

---

Backend never reaches Application startup complete

• Check RAM: docker info | grep -i memory (Docker needs ≥ 8 GB)
• Check for migration errors: docker compose logs backend | grep -i error
• Run migrations manually: docker compose exec backend python manage.py migrate

---

FATAL: password authentication failed for user "futureagi"

PG_PASSWORD was changed after the Postgres volume was initialized. Postgres sets the password only on first boot.

• Option 1: revert PG_PASSWORD to the original value
• Option 2 (data loss): docker compose down -v && docker compose up -d

---

code-executor crashes with clone: Operation not permitted

Host platform blocks privileged: true. Won’t work on Fargate, Cloud Run, or restricted Kubernetes. Use EC2, GCE, or bare metal. The rest of the stack runs, and only code-based eval features are unavailable.

---

Network and UI errors

Frontend blank page or CORS errors

VITE_HOST_API in .env doesn’t match the current backend URL. It’s written into config.js when the frontend container starts, so recreating the container is enough and no rebuild is involved:

docker compose up -d frontend

---

API calls fail with 502

Backend isn’t healthy. Check: docker compose logs backend and docker compose ps backend.

---

PeerDB errors

Mirrors show “not started” or don’t appear

PeerDB init ran before Django migrations completed. Fix:

docker compose logs -f backend      # wait for "Application startup complete"
docker compose run --rm peerdb-init

Verify at http://localhost:3001, where mirrors should show running.

---

Analytics data is stale

PeerDB replication has fallen behind. Check mirror lag in the PeerDB UI at http://localhost:3001. Re-run init if a mirror shows an error:

docker compose run --rm peerdb-init

---

Temporal errors

temporal-server keeps restarting

Almost always a Postgres issue. Check: docker compose logs postgres. If Postgres is OOM-killing, raise Docker RAM to ≥ 8 GB. If Postgres is healthy: docker compose restart postgres temporal

---

After an upgrade

Migration fails after git pull

docker compose exec backend python manage.py migrate

If a conflict persists, check the release notes for manual steps.

---

Everything worked before the upgrade, now it doesn’t

Roll back by pinning the image versions in .env to the previous release tag, then bringing the stack up again. Nothing is built locally, so a git checkout on its own changes no running code. The full procedure is in Upgrades & rollback.

# .env, pin all five to the previous release tag
FUTURE_AGI_VERSION=v1.25.0
FRONTEND_VERSION=v1.25.0
AGENTCC_GATEWAY_VERSION=v1.25.0
SERVING_VERSION=v1.25.0
CODE_EXECUTOR_VERSION=v1.25.0

docker compose up -d

---

Still stuck?

Open an issue at github.com/future-agi/future-agi/issues and attach all-logs.txt. Scrub any credentials before you upload it, since the dump includes container environments.

docker compose logs > all-logs.txt 2>&1
docker compose ps >> all-logs.txt

Dive deeper