A container that survives twelve seconds
The backoff resets, so the crash loop never slows down
always 12s
Docker Restart Policy Simulator
Work out when Docker restarts a container and how long it waits. Add a second line saying how long the container survives each time, because that number changes the answer completely.
Paste below, or drop a file anywhere on this panel
Or drop a file anywhere on this panel. Nothing is uploaded: the analysis runs in this tab.
The answer appears here
Paste on the left and press Simulate. Nothing leaves this tab.
Formatted
Results
Nothing else to flag.
No formatting problems, and nothing the rules object to. Worth remembering what that covers: this reads the file you pasted, not the account or cluster it will be applied to.
No finding matches that filter.
Examples
Real input you can load into the tool above. Each one shows a different thing going wrong, because that is what the tool is for.
The always policy
Comes back after a reboot even if you stopped it deliberately
always
on-failure with no number
Retries forever, which is always with an exception for a clean exit
on-failure
Common mistakes
These are the ones that fail silently. The config is accepted, nothing raises an error, and the consequence arrives later.
Using always when you mean unless-stopped
always brings the container back after a reboot even if you stopped it deliberately, which is the opposite of what stopping it meant.
Instead:Use unless-stopped for anything you might want to stop by hand.
Assuming the backoff will slow down a crash loop
The counter resets after ten seconds of uptime, so a container that runs for twelve seconds and dies restarts every twelve seconds at full speed forever.
Instead:Fix the crash. If it must be bounded, use on-failure:N, which counts regardless of uptime.
Expecting a restart policy to handle a hung process
It only reacts to the process exiting. A deadlocked container never exits, so it is never restarted.
Instead:Add a HEALTHCHECK for visibility, and something that acts on it if a restart is what you need.
Ten seconds of uptime resets the backoff
Docker doubles the restart delay from 100ms up to a minute, and throws the counter away once a container has run for ten seconds. A process that dies after twelve seconds restarts at full speed, forever.
The backoff, and when it does not apply
100ms, then 200, 400, 800, and so on to a one minute cap. That protects the host from a container that crashes instantly. It does nothing for a container that starts, works for a while and then dies, because the counter has already reset. That crash loop runs at full speed indefinitely and looks healthy in uptime terms.
always and unless-stopped differ in one situation
Both restart the container when it exits. The difference is what happens after you stop it by hand and then restart the daemon or reboot: always brings it back, unless-stopped leaves it stopped because Docker remembers the stop was deliberate. unless-stopped is what most people mean.
on-failure needs a number
Without one it retries forever, which is always with an exception for a clean exit. on-failure:5 bounds it, and the question worth asking is what should happen after the fifth attempt, because Docker's answer is nothing.
A restart policy only reacts to the process exiting
A container that is alive and wedged, deadlocked, out of file descriptors, or hung on a socket, is never restarted. From Docker's point of view nothing has happened.
A HEALTHCHECK does not fix that
It marks the container unhealthy, and plain Docker has no action attached to health. Acting on it needs Swarm, an orchestrator, or something external watching. So the health state is worth having for visibility and is not a restart mechanism.
The default is no
Which is why a container that exited overnight is simply gone in the morning, with nothing having retried it and nothing having said so.
Related docker tools
Docker Container Image Reference Parser Is that a registry or a Docker Hub user? Dockerfile Linter What this image will do to you later docker run to Kubernetes YAML And the flags that have no equivalent Docker Compose to Kubernetes And why depends_on has no equivalent Docker Logging Driver Generator json-file never rotates Dockerfile Non-Root USER Generator Numeric, or Kubernetes rejects it
All 36 docker tools