From 53cb9d0c70e33b778b84508a458f6d2638d33faa Mon Sep 17 00:00:00 2001 From: SnapOtter Date: Thu, 30 Jul 2026 10:17:43 +0800 Subject: [PATCH] docs(deployment): troubleshoot the off-network EAI_AGAIN crash-loop (#688) A retried compose up after a failed first start can leave the app container detached from the compose network; the resulting Postgres EAI_AGAIN crash-loop reads as a database problem and never self-heals. New Troubleshooting section with the force-recreate fix. Fixes #675. --- apps/docs/guide/deployment.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/apps/docs/guide/deployment.md b/apps/docs/guide/deployment.md index 778a3a15..dbc1f752 100644 --- a/apps/docs/guide/deployment.md +++ b/apps/docs/guide/deployment.md @@ -561,6 +561,24 @@ cloudflared tunnel --url http://localhost:1349 Note: Cloudflare has a 100 MB upload limit on free plans. Set `MAX_UPLOAD_SIZE_MB=100` to match. +## Troubleshooting {#troubleshooting} + +### "Postgres not reachable: EAI_AGAIN" right after a failed first start {#eai-again-after-failed-first-start} + +If the very first `docker compose up -d` fails partway (a port already in use is the usual reason), a plain `up -d` retry can start the app container without attaching it to the compose network. The app then crash-loops with: + +``` +Postgres not reachable: EAI_AGAIN +``` + +while `docker ps` shows postgres healthy. The error is real but points at the wrong container: without the network, DNS for the `postgres` hostname cannot resolve at all, and the restart policy replays the same failure forever. + +Fix whatever broke the first start (usually: free the port), then force the app container to be recreated so it reattaches to the network: + +```bash +docker compose up -d --force-recreate SnapOtter +``` + ## CI/CD {#ci-cd} The GitHub repository has three workflows: