DockerJunior
Compose service starts before its database is ready
depends_on only waits for a container to start. Use a healthcheck and condition: service_healthy so your app starts after the database is ready.
What you see
- The app container fails to connect to the database on
docker compose up, then works if you start it again later
What it means
Compose starts containers in dependency order, but by default it waits only until a dependency is running, not until it is ready. A database needs time after the process starts before it accepts connections.
How to confirm the cause
- 1Check the dependency's health status
docker compose ps
A service with a healthcheck shows its health state.
- 2Read the app's logs
docker compose logs web
Confirm the failure is a connection error at startup and not a bad password.
Causes and fixes
depends_on has no condition
- HOW TO TELL
- The compose file lists
depends_on: - dbonly. - FIX
- Add a healthcheck to the dependency and use
condition: service_healthyon the service that needs it.services: web: build: . depends_on: db: condition: service_healthy restart: true db: image: postgres:18 healthcheck: test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"] interval: 10s retries: 5 start_period: 30s timeout: 10s
How to stop it coming back
- Make the app retry its first connection with a delay. A healthcheck helps at startup but does not cover a database restart later.
- Use
service_completed_successfullyfor one-off setup jobs such as migrations.
Keep going
- Cheat sheet: Docker Compose
- Lesson: the containers topic in Learn
Sources
Docker documentation (docs.docker.com), read 18 Nov 2026 from the official docs repository.