Docker Compose depends_on does not wait for service to be ready

Problem

Application container starts before the database is ready to accept connections, even with depends_on defined. The app crashes with connection refused.

Symptoms

• Connection refused on startup
• App crashes before DB is ready
• depends_on only waits for container start, not service readiness

Stack

Solution

Use depends_on with condition: service_healthy and define a healthcheck on the database service. This makes Docker Compose wait until the healthcheck passes.

Code

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 2s
      timeout: 5s
      retries: 10

  app:
    build: .
    depends_on:
      db:
        condition: service_healthy

Caveats

healthcheck with condition requires Docker Compose v2. The old v1 format does not support conditions.