Problem: docker compose stack fails to start — dependency not ready (Connection refused / unhealthy / depends_on ignored) —— Trove problem library

What you will run into

After docker compose up, the dependent service (app) reports Connection refused (cannot reach the database/upstream), dependency failed to start: container xxx is unhealthy, or docker compose ps keeps showing unhealthy.

You wrote depends_on exactly like the tutorial says and it still fails — plain depends_on only guarantees start order, not readiness: the db container being up does not mean its port is connectable.

Why this happens

compose depends_on has two semantics: start order (short form depends_on: [db]: create/start db first, do not wait for readiness) and readiness condition (long form depends_on: db: condition: service_healthy: start app only after db's healthcheck passes).

Databases/middleware usually take seconds from "process started" to "port connectable" (locally reproduced: a python http.server stand-in for db needed a 4s sleep), so connections during that window are refused.

The readiness condition relies on a healthcheck: compose runs the test command every interval, marks the service unhealthy after retries consecutive failures, healthy on success.

up --wait waits for every service to become healthy (bounded by --wait-timeout).

Three high-frequency healthcheck pitfalls, all reproduced locally: ① test uses a binary that is not in the image (e.g.

alpine has no busybox httpd applet) → container exits 127, compose reports dependency failed to start ... exited (127);

② slow-starting service without start_period → startup failures count toward retries and it gets misjudged unhealthy (reproduced: service ready at 4s, interval 1s × retries 3 already killed it at ~3s);

③ the check command itself is wrong/always fails → ps shows Up x seconds (unhealthy) and up --wait times out.

Deterministic takeaway: on unhealthy, read docker inspect <container> --format "{{json .State.Health.Log}}" — the last entry's Output is the check command's real error; on exited (127), verify the test command exists in the image first.

Step by step

1. Classify the error first — Must do

• Connection refused: app started too early, dependency not ready → add healthcheck + condition: service_healthy.
• dependency failed to start ... is unhealthy: healthcheck failing → go to step 2.
• dependency failed to start ... exited (127): healthcheck command missing from the image → change command or image.

2. Find out why the healthcheck fails — Must do

docker compose ps                      # which service is unhealthy
docker inspect <container> --format "{{json .State.Health.Log}}" | tail -c 800

The last log entry's Output is the real error from the check command (locally we saw the urllib ConnectionRefused traceback).

3. Verify the test command exists in the image — Must do

docker run --rm <image> sh -c "which <command>"    # not found -> switch command

Counter-example reproduced: alpine has no busybox httpd (httpd: applet not found, exit 127).

4. Add start_period for slow-starting services — By diagnosis

If the service needs a few seconds to become ready, start_period must exceed that time; otherwise startup failures count toward retries and it gets misjudged unhealthy (reproduced: a 4s-ready service was killed at ~3s without start_period).

5. Accept with up --wait — Must do

docker compose up -d
docker compose up --wait --wait-timeout 60    # fail on timeout, never wait forever

How to confirm it works

docker compose up --wait --wait-timeout 60 exits 0; docker compose ps shows Up x seconds (healthy) for every service;

the app log no longer shows Connection refused and business calls succeed (reproduced: app printed APP_OK right after db became healthy).

Other environments

Symptom

app-1  | wget: can't connect to remote host (172.18.0.3): Connection refused
app-1  | APP_CONN_REFUSED

db-1  | httpd: applet not found
db-1 exited with code 127
dependency failed to start: container depstest-db-1 exited (127)

Container depstest-db-1  Waiting
Container depstest-db-1  Error
dependency failed to start: container depstest-db-1 is unhealthy

Signature: you wrote depends_on and still get connection refused; or ps shows unhealthy; or the container exits 127.

Cause

Plain depends_on guarantees start order only, not readiness. Readiness requires a healthcheck plus condition: service_healthy. Healthcheck failures come from three sources: command missing from the image (exit 127), slow start without start_period (misjudged unhealthy), or a broken check command itself (permanently unhealthy).

Solution

1. Add a healthcheck to the dependency (test command must exist in the image; add start_period for slow starts);
2. Switch app to depends_on: db: condition: service_healthy;
3. docker compose up -d then accept with docker compose up --wait --wait-timeout 60;
4. On unhealthy, docker inspect <container> --format "{{json .State.Health.Log}}" to see the check command's real error.

Related canonicals

Read in order: precondition -> same root / same domain / related:

• Precondition (rule out first):
• docker compose / docker compose command not found (same domain: prerequisite of the compose startup chain)

• Related (similar errors, different cause):
• Docker daemon unreachable (the daemon must be alive first; connection errors surface before compose semantics)