How to fix dependency failed to start in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 820 views

This error occurs when a container that another service depends on fails its health check and is marked as 'unhealthy'. Docker Compose stops waiting and prevents the dependent service from starting, requiring you to fix the unhealthy dependency or adjust health check timing.

Quick fix

Fixes dependency failed to start

# View container logs
docker compose logs <service-name>

# Check health check status in detail
docker inspect --format='{{json .State.Health}}' <container-name> | jq

# Or without jq
docker inspect <container-name> | grep -A 20 "Health"
  1. Inspect the unhealthy container logs
  2. Increase the health check start_period
  3. Verify the health check command works
  4. Fix common service initialization issues
docker — error
# View container logs
docker compose logs <service-name>
# Check health check status in detail
docker inspect --format='{{json .State.Health}}' <container-name> | jq
# Or without jq
docker inspect <container-name> | grep -A 20 "Health"
dependency failed to start

What this error means

The "dependency failed to start" error in Docker Compose indicates that a service your application depends on could not reach a healthy state within the allowed time. When you use `depends_on` with `condition: service_healthy`, Docker Compose waits for the dependency's health check to pass before starting your service. If the dependency exhausts all health check retries while still unhealthy, Docker Compose reports "dependency failed to start: container [name] is unhealthy" and stops the startup process entirely. This is expected behavior introduced in Docker Compose v2.22.0+ to fail fast rather than leave you with partially running stacks. The root cause is typically one of two things: either the dependency service itself has a problem (configuration error, missing files, resource constraints), or the health check parameters are too aggressive for the service's actual startup time.

Typical symptoms

  • Running 'docker compose up' fails with 'dependency failed to start: container [name] is unhealthy'
  • Service A refuses to start because Service B never becomes healthy
  • Health check shows 'starting' status indefinitely, then fails
  • The same compose file worked before but now fails after Docker updates
  • CI/CD pipelines fail at container startup with dependency errors
  • Manual inspection shows the dependency container is actually running

Common causes

  1. Health check start_period is too short for the service to initialize
  2. Dependency service has a configuration error and cannot start properly
  3. Health check command is incorrect or the health endpoint doesn't exist
  4. Resource constraints (CPU/memory limits) slow down service startup
  5. Database migration or initialization scripts take longer than expected
  6. Network issues prevent the health check command from succeeding
  7. Missing environment variables or secrets cause the service to fail
  8. Volume permissions prevent the service from writing required files

How to fix "dependency failed to start"

1Inspect the unhealthy container logs

First, identify why the dependency is unhealthy by checking its logs and health check status:

bash
# View container logs
docker compose logs <service-name>

# Check health check status in detail
docker inspect --format='{{json .State.Health}}' <container-name> | jq

# Or without jq
docker inspect <container-name> | grep -A 20 "Health"

Look for:
- Application startup errors
- Missing configuration or environment variables
- Permission denied errors
- Connection failures to external services

The health check output shows the exit codes and output of each health check attempt, which reveals exactly why it's failing.

2Increase the health check start_period

The start_period defines how long Docker waits before counting failed health checks against the retry limit. If your service takes time to initialize, increase this value:

yaml
services:
  db:
    image: postgres:15
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 60s  # Increased from default 0s

Recommended values by service type:
- Simple databases (Redis, Memcached): 10-20s
- PostgreSQL/MySQL: 30-60s
- Elasticsearch/MongoDB: 60-120s
- Applications with migrations: 60-180s

During the start_period, failed health checks don't count toward the retry limit, giving slower services time to initialize.

3Verify the health check command works

Test the health check command manually inside the container to confirm it works:

bash
# Start just the dependency service
docker compose up -d db

# Execute the health check command manually
docker compose exec db pg_isready -U postgres

# For HTTP health checks
docker compose exec app curl -f http://localhost:8080/health

Common health check commands:

yaml
# PostgreSQL
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres}"]

# MySQL
test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-p${MYSQL_ROOT_PASSWORD}"]

# Redis
test: ["CMD", "redis-cli", "ping"]

# Generic HTTP
test: ["CMD", "curl", "-f", "http://localhost:8080/health"]

# MongoDB
test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]

If the command fails, check that:
- Required tools (curl, pg_isready) are installed in the image
- The service is listening on the expected port
- Authentication credentials are correct

4Fix common service initialization issues

Address the underlying problems that prevent the service from becoming healthy:

Database initialization is slow:

yaml
services:
  db:
    image: postgres:15
    volumes:
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      start_period: 120s  # Allow time for init scripts

Missing environment variables:

yaml
services:
  app:
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/mydb
      - REDIS_URL=redis://redis:6379
    env_file:
      - .env  # Make sure this file exists

Permission issues with volumes:

bash
# Fix ownership on Linux
sudo chown -R 1000:1000 ./data

# Or use a named volume instead
volumes:
  db_data:

Resource constraints:

yaml
services:
  db:
    deploy:
      resources:
        limits:
          memory: 1G
        reservations:
          memory: 512M
5Adjust retry count and intervals

Fine-tune the health check parameters to give services more time:

yaml
services:
  db:
    image: postgres:15
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s      # Check every 5 seconds
      timeout: 10s      # Wait 10s for response
      retries: 10       # Try 10 times after start_period
      start_period: 30s # 30s grace period

Understanding the timing:
- start_period: Grace period before retries count (30s)
- interval: Time between checks (5s)
- retries: Max failures after start_period (10)
- timeout: How long to wait for each check (10s)

Total wait time = start_period + (retries * interval) = 30s + (10 * 5s) = 80s

Increase these values for services that need more initialization time.

6Use service_started instead of service_healthy (temporary workaround)

If you need to get the stack running while debugging, temporarily use service_started instead of service_healthy:

yaml
services:
  app:
    depends_on:
      db:
        condition: service_started  # Only waits for container to start
        # condition: service_healthy  # Commented out for debugging

  db:
    image: postgres:15
    # healthcheck still defined for monitoring
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

Important: This is a workaround, not a fix. Your application should handle connection retries gracefully. Consider adding retry logic:

yaml
services:
  app:
    command: ["./wait-for-it.sh", "db:5432", "--timeout=60", "--", "npm", "start"]

Or implement connection retry logic in your application code.

Advanced notes

Behavior change in Docker Compose v2.22.0+: Earlier versions would continue waiting indefinitely if a dependency became unhealthy but the container kept running. Newer versions fail fast when health checks exhaust their retries, which is why you may see this error appear after Docker updates.

Using restart policies with health checks: Combine health checks with restart policies to auto-recover from transient failures:

yaml
services:
  db:
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      retries: 3
      start_period: 30s

The `required: false` option: Make a dependency optional so your service starts even if the dependency fails:

yaml
depends_on:
  cache:
    condition: service_healthy
    required: false  # App starts even if cache is unhealthy

Debugging health checks in CI/CD: Add verbose health check output for CI environments:

yaml
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U postgres || (echo 'Health check failed' && exit 1)"]

Docker events for monitoring: Watch health transitions in real-time:

bash
docker events --filter 'type=container' --filter 'event=health_status'

Multi-stage dependencies: For complex startup orders, consider using init containers or startup scripts rather than relying solely on health checks:

yaml
services:
  db-init:
    image: postgres:15
    command: ["psql", "-h", "db", "-U", "postgres", "-c", "SELECT 1"]
    depends_on:
      db:
        condition: service_healthy

  app:
    depends_on:
      db-init:
        condition: service_completed_successfully

Frequently asked questions

What does "dependency failed to start" mean?
The "dependency failed to start" error in Docker Compose indicates that a service your application depends on could not reach a healthy state within the allowed time. When you use depends_on with condition: service_healthy, Docker Compose waits for the dependency's health check to pass before starting your service. If the dependency exhausts all health check retries while still unhealthy, Docker Compose reports "dependency failed to start: container [name] is unhealthy" and stops the startup process entirely.
How do I fix "dependency failed to start"?
This error occurs when a container that another service depends on fails its health check and is marked as 'unhealthy'. Docker Compose stops waiting and prevents the dependent service from starting, requiring you to fix the unhealthy dependency or adjust health check timing.
What causes "dependency failed to start"?
Health check start_period is too short for the service to initialize Dependency service has a configuration error and cannot start properly Health check command is incorrect or the health endpoint doesn't exist
Is the "dependency failed to start" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading