Starting a process does not make its dependency usable
A database container can be running while its service is still initializing. An application that assumes otherwise can fail during a cold start even though a later manual restart succeeds. A reliable Compose setup makes the startup contract explicit and gives the application a bounded response to dependencies that become unavailable later.
Compose can wait for a dependency's healthcheck when the relationship uses service_healthy. That ordering does not replace runtime resilience. A dependency can fail after the application starts, and a green container healthcheck may test a narrower operation than the application needs.
Setup: define what readiness actually means
Record the Compose version, services, dependency relationships and the first failing application operation. Identify whether the application needs merely a reachable port, an authenticated database session or a schema that a separate migration step prepares. Use an approved test environment for cold-start experiments.
An illustrative dependency fragment is:
services:
app:
depends_on:
db:
condition: service_healthy
The referenced db service also needs its own meaningful healthcheck. This fragment alone is not a complete deployment. Keep secrets out of copied command examples and choose a check whose credentials and permissions are appropriate to its limited purpose.
Illustrative incident: a manual restart hides the race
In this fictional example, a web application fails its first database connection after a host restart. Operators restart the application a minute later and it works, so they assume the earlier failure was random. The database had not completed the readiness work the application expected when the first connection occurred.
The investigation preserves startup timestamps from both services and defines an explicit readiness check. It also reviews the application's retry and reconnection behavior. A fixed sleep might hide one timing pattern while failing again on a larger dataset or slower recovery path.
Troubleshooting: compare startup and runtime behavior
| Observation | Evidence | Question |
|---|---|---|
| Cold start fails but later restart works | Dependency and application timelines | Did the application start before usable readiness? |
| Healthcheck passes but business request fails | Actual probe and required operation | Does the probe test the necessary boundary? |
| Dependency restarts break an established app | Connection and retry behavior | Can the application recover after startup? |
| Readiness never succeeds | Healthcheck output and service logs | Is the check correct and the service actually healthy? |
Compose's dependency restart option concerns supported explicit Compose operations; do not assume it implements every possible runtime failure response. Distinguish container restart policy, dependency startup conditions and application-level connection recovery in the design review.
Implement a bounded readiness contract
Add a service-specific healthcheck and the intended dependency condition. Set realistic startup allowances based on observed initialization, while keeping an upper bound that reveals a genuinely stuck service. If migrations are separate, define their completion and failure behavior explicitly rather than letting all application replicas race to modify a schema.
Implement limited, observable retries for transient connection failures in the application. Fatal configuration or authentication errors need a clear failure signal rather than an endless retry loop. Preserve logs and ensure restarting a service does not silently rerun non-idempotent initialization work.
Verification, monitoring and SOP
Test an empty-environment cold start, a normal restart and a controlled dependency interruption. Verify a representative business request, not only container status. Check that failures become visible and that recovery does not duplicate initialization effects.
Monitor readiness duration, restart loops and dependency connection errors. An internal SLO can define startup acceptance under specified recovery conditions; an external SLA needs separate service commitments. The SOP should list probe ownership, startup bounds, retry policy, migration sequencing, test cases and rollback to the last known compatible configuration.
See Clouvenix docker consulting for a reviewed implementation and operational handover.
Technical reference
Docker Compose startup order, Docker container execution concepts. Reviewed 19 October 2026; use documentation for the installed product and release.