A deployment dashboard marks a container unhealthy, and the first instinct is often to restart it. That can clear useful evidence without fixing the cause. In Docker, begin by reading the health check result and finding out what the check actually ran.
Read the recorded check
For a container named api, run docker inspect –format '{{json .State.Health}}' api. The output includes the health status and recent check results, including exit codes and available command output. If the container has no health check configured, there will be no recorded health history to inspect.
Next, compare the check’s timestamps and output with application logs using docker logs –since 10m api. Look for a repeated failure at the same interval, a startup that takes longer than the configured start period, or an error that points to a specific dependency. A health check can fail while the application process is still running.
Check the probe’s assumptions
Review the image or Compose configuration to see the exact health check command, its interval, timeout, retries, and start period. Then ask whether that command is available inside the image and whether it checks the right address and port. Minimal images often omit tools such as curl, so a probe copied from a fuller base image may fail even when the service is responding.
The probe also runs in the container’s own environment. A check aimed at localhost tests the container’s local service, not whether another container can resolve the service name or whether an external load balancer can reach it. If the failure only appears outside the container, investigate that network path separately instead of broadening the probe until it passes.
Change one variable at a time
Reproduce the health check command in the same container context where possible, then change one assumption at a time: command availability, address, expected response, or timing. Record the result after each change. This keeps a probe correction distinct from an application fix.
An unhealthy status does not, on its own, mean Docker has restarted the container; restart behavior depends on the container’s exit state and the surrounding orchestrator’s configuration. Compose can also use health status to control dependent service startup when configured to do so. Check that behavior explicitly before assuming a restart policy will respond to a failed probe.