Docker Core
Compose gave up because a dependency container failed its startup condition.
dependency-failed-to-startReviewed for reference consistency: August 11, 2026
Compose gave up because a dependency container failed its startup condition.
What dependency-failed-to-start Means
The dependency-failed-to-start error on the Docker Core indicates compose gave up because a dependency container failed its startup condition.. This typically occurs due to the dependency's health check command fails persistently.
Compose supports ordering through dependency conditions, including waiting for a service to report healthy. When the dependency's health check never passes within its window, startup aborts with the dependency-failed-to-start line naming the container that stayed unhealthy.
How to fix dependency-failed-to-start
General informational guidance, not professional advice. Commands can affect your system or data — back up first and proceed at your own risk. FixerCode is an independent reference, not affiliated with any vendor mentioned.
Read the dependency container's own logs
The tail of the named service's logs shows its real startup progress and the failing probe's context.
docker compose logs --tail 50 <service>Show health status across the project
The compose ps view includes health state per service, separating unhealthy dependencies from unstarted dependents.
docker compose ps
Technical Background
Conditions turn startup into a gate: a dependency declared with a healthy condition becomes a hard prerequisite, converting a would-be runtime connection error into a clean startup abort.
Health status is computed by the engine from the healthcheck definition in the image or the compose file; a failing probe is application-level truth, so the explanation lives in the dependency's own logs rather than in the ordering declaration.
Common Causes
- The dependency's health check command fails persistently
- The start period is shorter than real initialization time
- The healthcheck probes an endpoint that opens late
Typical Scenarios
- An app service depending on a database whose healthcheck script is wrong
- A first boot where the dependency needs longer than the configured start period
- A healthcheck hitting an endpoint the app only exposes after migrations
What to Know
The naming is precise: the line identifies the dependency container, whose log tail then explains why the probe kept failing, while the dependent service was never started at all.
Frequently Asked Questions
Common questions about Docker dependency-failed-to-start error
It was never created. The gate prevents creation of the dependent container when the condition fails, so its absence from the process listing is expected.
Ordering alone only sequences creation; readiness gating requires the condition form backed by a healthcheck.
Related Error Codes
The daemon could not bind the published host port because another holder keeps it.
An exec or attach targeted a container whose main process is not active.
BuildKit aborted the build because a step exited with a failing code.
Related Errors From Other Categories
Similar error codes documented across different platforms and systems