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.
More 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 Docker OCI Image Labels Generator One of them actually does something Docker Hub Pull Rate Limit Calculator Counted per IP, not per person Docker Registry Storage Calculator Deleting a tag frees nothing Docker Build Context Analyzer All of it uploads before anything runs Docker Compose to docker run Converter Names stop resolving Docker Compose Version Migrator version: is obsolete now Docker Compose Network and Port Viewer Everything reaches everything Docker Command Explainer Which flags hand over the host Docker BuildKit Cache Mount Generator apt deletes the cache you just mounted Docker BuildKit Secret Mount Generator ARG is in docker history forever Docker .dockerignore Pattern Tester *.log does not match logs/app.log Docker Image Manifest Viewer unknown/unknown is not broken Docker Image Config Viewer Anyone who can pull can read your Env Docker Registry Token Decoder Check the scope before the credentials Docker HEALTHCHECK Generator Docker does nothing when it fails Docker Network Subnet Calculator 31 networks, then it stops Docker History Analyzer The rm did not save anything Docker Run to Compose Converter Some flags have no equivalent Docker CMD and ENTRYPOINT Tester Why docker stop takes ten seconds Docker Port Mapping Tester -p reaches past your firewall Docker -v to --mount Converter -v invents missing directories Docker Exit Code Explainer 137 is two different problems Docker CPU Limit Converter --cpu-shares limits nothing Docker Memory Limit Calculator -m 512m allows a gigabyte Docker Compose Interpolation Tester An unset variable is an empty string Docker Environment Variable Precedence Tester Your shell does not reach the container Docker Compose Override Merge Previewer An override can add a port, never remove one Dockerfile Multi-Stage Build Analyzer Which stages reach the image Dockerignore Validator It is not .gitignore