A Docker container can still be running even when its application is no longer able to serve requests. Docker’s HEALTHCHECK instruction runs a probe and records whether that application-level check succeeds. It can expose a failure that process status misses, but it does not restart the container by itself.
Why a running container can still be broken
Docker’s container state and an application’s ability to serve useful work are different signals. A process can remain alive while a web server stops responding, a database is not ready, or a service becomes otherwise unusable. Docker describes HEALTHCHECK as a way to test whether a container is still working; the check is only as meaningful as the behavior it probes. Dockerfile reference
As an Amazon Associate I earn from qualifying purchases.
A healthcheck runs a command inside the container. Exit status 0 marks the container healthy, 1 marks it unhealthy, and 2 is reserved. The command must exist in the image, and its success or failure should reflect something the application needs to do—not merely that a process exists.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Add a Dockerfile healthcheck
Docker’s reference gives this HTTP probe as a syntax example:
#1 Best Overall
HEALTHCHECK --interval=5m --timeout=3s
CMD curl -f http://localhost/ || exit 1Before using it, confirm that curl is installed in the image, the endpoint is reachable from inside the container, and that the endpoint represents the service behavior you care about. The -f option makes curl fail for an unsuccessful HTTP response; the shell expression ensures a failed request produces a nonzero status.
A healthcheck can use Dockerfile shell form or exec-array form. If a Dockerfile contains more than one HEALTHCHECK instruction, only the last one takes effect. Dockerfile reference
Choose probe timing deliberately
The timing values determine how often Docker checks, how long it waits for one check, how much bootstrap time it allows, and how many consecutive failures it tolerates. Docker’s documented defaults are configuration defaults, not universal recommendations.
| Setting | Docker default | What it controls |
|---|---|---|
interval |
30 seconds | Time between checks. A check runs first after the interval and then at the configured interval after the previous check completes. |
timeout |
30 seconds | Maximum time allowed for a probe. Docker stops a probe that exceeds this limit with SIGKILL. |
start_period |
0 seconds | Initial allowance for startup. Failures during this period do not count toward the retry limit until a probe succeeds; after that first success, later consecutive failures count. |
start_interval |
5 seconds | Probe cadence during the start period. This option requires Docker Engine 25.0 or later. |
retries |
3 | Number of consecutive failures needed before Docker marks the container unhealthy. |
These defaults are documented in Docker’s Dockerfile reference. A shorter interval can detect trouble sooner but runs checks more often; a longer timeout or higher retry count can reduce false alarms from brief delays while increasing detection time. Set a start period long enough for the application’s normal initialization, rather than treating it as extra time for an application that is already serving and then fails.
Check the behavior that matters
Prefer a probe that tests the service’s useful function. Docker’s examples include an HTTP request, redis-cli ping, and pg_isready. Dockerfile reference Docker Compose Quickstart
- A web service probe should call a local endpoint that reflects the ability to serve the relevant request, not simply test whether a port is open.
- A Redis probe can use
redis-cli ping, if that client is present in the image and its result represents the readiness you need. - A PostgreSQL readiness probe can use
pg_isready, with the appropriate connection parameters and credentials for the container.
There is no single best probe for every image. An overly shallow check can say healthy while users still fail; a check that depends on an absent utility will fail for reasons unrelated to the application. Keep the command lightweight and ensure its failure status is nonzero.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Use Compose to wait for a healthy dependency
In Compose, short-form depends_on orders startup but only ensures that a dependency has started. It does not wait for the dependency’s healthcheck. Use long form with condition: service_healthy when a dependent service must wait for a healthcheck to pass before it is created. Control startup and shutdown order in Compose
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →services:
web:
build: .
depends_on:
db:
condition: service_healthy
db:
image: postgres:18
healthcheck:
test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
interval: 10s
retries: 5
start_period: 30s
timeout: 10sThis follows Docker’s documented startup-order example. The doubled dollar signs in the Compose command prevent Compose from interpolating those variables itself, leaving the container shell to expand them. These timing values are example settings, not general requirements. Control startup and shutdown order in Compose
Best Value
Compose can override a healthcheck inherited from an image. Its test may be a string, equivalent to CMD-SHELL, or a list beginning with CMD, CMD-SHELL, or NONE. Use NONE or disable: true to disable an inherited check. Docker Compose’s services reference marks healthcheck duration support—including interval, timeout, start period, and start interval—as introduced in Compose 2.20.2. Define services in Docker Compose
What an unhealthy status does—and does not do
A healthcheck reports and records health; it is not a restart policy. Docker’s restart policies concern container exit behavior, and an unhealthy status alone does not cause Docker to restart the container. If automatic recovery is required, a separate controller or orchestration mechanism must act on health state.
Compose’s long-form depends_on also has an optional restart: true behavior for explicit Compose-controlled dependency updates or restarts; Docker documents that it does not apply to automated container-runtime restarts. It should not be confused with restarting a container just because a healthcheck reports it unhealthy. Define services in Docker Compose
Inspect a failed probe
Docker stores brief output from probe standard output or standard error in the container’s health status; the Dockerfile reference says the stored output is currently limited to the first 4096 bytes. A health-status change also generates a health_status event. These details can help distinguish a bad endpoint, missing command, or timeout from an application failure. Dockerfile reference
If a container reports unhealthy, verify that the probe command runs in the image, test the exact target from inside the container, and compare the observed check duration with its timeout. Then adjust the probe or timing only if the result matches the intended definition of ready and healthy.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
