Docker Unhealthy but Still Running? Check What Triggers a Restart
An unhealthy label does not mean Docker will restart a container. Inspect process state, probe output and dependencies before choosing a recovery action.
RB
Imagine this hypothetical deployment: your API has been running since breakfast, Docker shows Up ... (unhealthy), and requests are timing out. The Compose file already says restart: unless-stopped. Waiting for another restart feels reasonable—but the process never stopped.
An unhealthy Docker container does not automatically restart under a standard Docker Engine restart policy. A health check reports whether its probe succeeds; a restart policy responds to container exit and, depending on the policy, daemon restart. First establish which event actually happened. Then choose a recovery action that addresses the failure. Docker documents restart policies separately from health checks.
This guide covers a single Docker Engine host, including Compose workloads on a self-managed Krova Cube. Swarm and Kubernetes have different controllers and need their own recovery analysis.
Start with identity, process state and probe evidence
Before changing the restart policy, find the exact container. A service name can point to a replacement after a deployment; keep the container ID with the evidence so you do not compare two different instances.
docker ps -a --no-trunc --format 'table {{.ID}}\t{{.Names}}\t{{.Status}}'
# Replace this with the container ID from the listing.
target=YOUR_CONTAINER_ID
docker inspect --type=container --format \
'id={{.Id}} status={{.State.Status}} running={{.State.Running}} restarts={{.RestartCount}} policy={{.HostConfig.RestartPolicy.Name}}' "$target"
docker inspect --type=container --format '{{json .Config.Healthcheck}}' "$target"
docker inspect --type=container --format '{{json .State.Health}}' "$target"
docker logs --since 10m --tail 100 "$target"These are read-only diagnostics, offered as examples rather than results from a tested Krova workload. docker inspect supports selecting container objects and formatting specific fields. Read the configured health command alongside its recent output, exit codes and timestamps. Logs are useful only if the application sends relevant messages to Docker's logging path. Redact credentials or tokens before sharing probe output or logs.
If no health check is configured, missing health data is not evidence that the application is healthy. If running=true and health is unhealthy, you have two observations that can both be correct: the container process is alive, while the configured probe has failed.
A failed probe is a clue, not the diagnosis
Docker's HEALTHCHECK reference describes a command that runs inside the container. Its result produces a separate health status. Check the actual command, not the health check you remember writing: an image change may have removed its executable, or the probe may target the wrong port or path.
Next ask what the endpoint promises. A shallow liveness endpoint might only show that a process can answer. A readiness endpoint might fail because a database is unavailable. Neither observation, by itself, tells you that restarting the API will restore service.
That distinction changes the next action. If the probe command is wrong, fix the configuration and deploy it deliberately. If a shared dependency is down, investigate that dependency and the application's reconnect behavior. Restarting every dependent container can add connection churn without repairing the cause. If the process itself is wedged and your runbook identifies a restart as recovery, capture enough evidence first and account for work in flight.
Also check the service through its normal permitted client route. A successful localhost probe cannot establish that DNS, TLS, the reverse proxy and the application's real request path all work. Do not expose a private health endpoint just to run this check. If resource pressure is a plausible cause, Krova's Docker CPU throttling walkthrough covers a separate diagnostic branch.
Why changing the restart policy may change nothing
For a running-but-unhealthy process, switching from unless-stopped to always does not create a health-triggered restart. Both are restart policies, not a rule that translates a failed health probe into a process exit. on-failure concerns a nonzero container exit; a failing health-check command is not the same event. See Docker's policy definitions and caveats.
If the container really is exited, follow that branch instead: inspect its exit state, policy and recent logs, and check whether an operator intentionally stopped it. Do not make an application exit whenever any dependency check fails without considering transient outages, retry behavior and durable work. That design can turn one dependency failure into repeated application restarts.
Compose startup ordering solves a different problem
It is easy to read too much into depends_on: condition: service_healthy. Compose's startup-order guide explains that Compose can wait for a dependency's health check before creating the dependent service. The nested restart: true example concerns explicit Compose operations on that dependency. These settings do not establish a general controller that restarts a running service whenever its health changes.
Use startup dependencies to express startup needs. For migration ordering and pre-start work, see Krova's Compose pre-start hook versus migration-job guide. Runtime recovery still needs an explicit owner and a failure model.
Decide who owns recovery before automating it
For this hypothetical API, the useful outcome is a small decision record: which container failed, what the probe reported, whether the process exited, what an external request showed, and why the chosen action should help. That record is more useful than a policy change made solely to make the status green.
- Probe configuration failed: repair the probe or image, deploy with a rollback path, and verify the intended request.
- Dependency failed: restore or route around the dependency using the application's documented recovery behavior.
- Process-local failure: follow a controlled recovery procedure that accounts for in-flight requests and durable jobs.
- Automatic recovery is justified: name its owner, bound retries, add a cooldown and escalation, and preserve evidence before repeated restarts.
Those are operational recommendations, not Docker guarantees. A recovery loop needs a stopping condition; otherwise it can keep destroying the evidence you need. After any action, verify the user-facing operation as well as the health label. Your next step is to capture one failing container's state and probe output, then choose the matching branch.
Run a Docker workload on Krova Cube
Krova supports standard Docker Engine and Compose inside Cube. Review the deployment model and plan your application's probes and recovery procedures alongside it.
Creation context: this article and its illustrative cover were produced with AI assistance. The opening situation is hypothetical; the command examples were checked against the linked documentation, not executed against a customer deployment.




