Docker Compose "depends_on" Condition Error - Fix Startup Order

Compose ordering with depends_on conditions fails in two ways: the YAML is malformed, or the dependency never reaches the condition (usually service_healthy) you required.

What this error means

docker compose up either rejects the file with a depends_on validation error, or starts and then aborts with dependency failed to start: container X is unhealthy / did not complete successfully.

service "api" depends on undefined service "databse"
# or at runtime:
dependency failed to start: container db is unhealthy

Common causes

Invalid long-form depends_on syntax

The condition form requires a mapping with condition: per service. A typo, a missing condition, or a referenced service name that does not exist fails validation.

service_healthy without a healthcheck

condition: service_healthy requires the dependency to define a HEALTHCHECK. Without one it has no health state and the condition can never be met.

The dependency never becomes healthy

The dependency starts but its healthcheck keeps failing, so the dependent service is never released and the run aborts.

How to fix it

Use valid long-form conditions

Reference existing services and give each a valid condition; ensure healthchecks exist for service_healthy.

services:
  api:
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 10s
      retries: 5
      start_period: 30s

Diagnose a stuck dependency

1. Run docker compose ps to see which service is unhealthy.
2. Inspect its health log to see the failing probe.
3. Either fix the probe/start period or relax to condition: service_started if health is not required.

How to prevent it

• Define healthchecks on any service used with service_healthy.
• Keep service names consistent between depends_on and definitions.
• Set realistic start periods so slow dependencies pass health in time.

Related guides