Troubleshooting

About

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 into any container

---

Startup errors

Cannot connect to the Docker daemon Docker isn’t running. Start Docker Desktop (Mac/Windows) or sudo systemctl start docker (Linux).

---

First build takes 15+ min or hangs on uv pip install Normal on first boot. If stuck >20 min, cancel and retry:

docker compose build --no-cache backend

---

ERROR: not enough free space Docker Desktop’s virtual disk is full. Settings → Resources → Disk image size → raise to 100 GB+. Or prune: docker system prune -af && docker builder prune -af

---

Port already in use

lsof -i :3000   # find the conflicting process
# or override in .env:
FRONTEND_PORT=3100
BACKEND_PORT=8100

---

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 — 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. Rebuild:

docker compose build --no-cache frontend
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 bash /setup.sh

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

---

Analytics data is stale PeerDB replication has fallen behind. Check mirror lag in the PeerDB UI. Re-run init if a mirror shows an error:

docker compose run --rm peerdb-init bash /setup.sh

---

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

git log --oneline -5
git checkout <previous-hash>
docker compose build && docker compose up -d

---

Still stuck?

Open an issue at github.com/future-agi/future-agi/issues with:

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

Next Steps