Compose Depends On Starts First but the Database Is Not Ready

Ordinary dependency startup order does not prove application readiness. Use a meaningful dependency healthcheck with condition: service_healthy when the dependent service must wait for that signal, and keep application retry handling for later failures.

Inspect the boundary before changing the service

The commands below use placeholder names. They illustrate a diagnostic workflow and were not run against a live container in this review. Match the Docker context and project before inspecting your own service.

# Fragment to adapt to the real service, not a complete deployment:
services:
  web:
    depends_on:
      db:
        condition: service_healthy
  db:
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "app", "-d", "app"]
      interval: 10s
      timeout: 5s
      retries: 5

What to compare

A process can be running while initializing storage, applying setup or opening its listener. A port being open can also precede the specific capability your application requires. The healthcheck must run in an environment containing its probe executable and must test the intended service. The example names PostgreSQL tooling; copying it into a different database image produces a failing check rather than a readiness guarantee.

Choose the next action

Choose the condition according to the dependency: service_started for a running process, service_healthy for the configured health signal, or service_completed_successfully for a one-shot prerequisite. Inspect healthcheck output and timing in a staging environment before relying on the gate. If migrations are required, decide whether they belong in a separate completed task rather than treating a generic database readiness probe as proof of schema readiness. Make timeout and retry budgets fit observed startup time.

Limits and verification

Startup gating does not provide permanent supervision of dependency availability. A database can fail after the web service starts, so the application still needs bounded reconnection and useful errors. The YAML above is an illustrative fragment and was not deployed. Confirm image-specific credentials and probe availability without placing passwords in shared logs. A fixed sleep is a timing guess, not a readiness test.

Related: Docker Exec Says the Container Is Not Running: Inspect the Original Exit.

Official Docker documentation checked November 10, 2026 (KST). Docker Compose 2.35.1 configuration parsing was available, but the Docker daemon was not running. These pages do not claim a live container connectivity, storage, health or recovery test.