Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsA container that keeps restarting has almost always recorded why its process stopped. The restart policy only decides whether Docker starts it again. To find the cause, preserve the logs and state first, read the exit code, build a short timeline of lifecycle events, and then check the host and the Docker daemon if the container itself reveals little.
Preserve the evidence before changing anything
Do not remove or recreate the container yet. By default, Docker keeps a stopped container’s filesystem, which helps debugging. A container started with --rm is deleted when it exits, along with its anonymous volumes, and that can destroy the only record of the failure. A restart does not create a new container, so logs from several attempts accumulate in one stream.
- List the container and note its name, image, command, and status. A crash-looping container usually shows a status such as
Restarting.docker ps -a - Capture recent output with timestamps so you can line it up with events later.
docker logs --timestamps --tail 200 <container> - Save the full inspected state.
docker inspect <container> > crash-state.json
In the inspect output, the most useful fields sit under State (exit code, error text, OOM status, start and finish times) plus RestartCount and the configured restart policy. To pull the key values in one line:
docker inspect --format 'exit={{.State.ExitCode}} oom={{.State.OOMKilled}} error={{.State.Error}} restarts={{.RestartCount}} finished={{.State.FinishedAt}}' <container>If the CLI rejects a flag, run the subcommand’s help for your installed version; option sets vary between releases.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
Read the exit code as a pointer, not a diagnosis
The exit code tells you which layer last reported a failure. Docker’s documented docker run statuses give the first branch to check:
| Exit code | Meaning in Docker’s documented cases | Where to look first |
|---|---|---|
| 125 | Docker itself failed to run the container | The error printed by docker run, invalid flags, daemon-side problems |
| 126 | The specified command was found but could not be invoked | Executable permissions, a file that is not a valid executable for the image’s architecture, script line endings and interpreter path |
| 127 | The specified command could not be found | Entrypoint and command override, the executable’s path inside the image, PATH |
| 137 | The process received SIGKILL | See the section below before drawing any conclusion |
Other nonzero codes come from the application and mean whatever it defines them to mean. Match them against the log lines from the same timestamps.
Exit 137 needs correlation
Exit 137 tells you that something sent SIGKILL. Docker’s container-list reference lists several possible senders, including manual termination and a daemon restart, so 137 alone does not prove an out-of-memory kill. Use the other evidence to narrow it down:
Rank #2
- OOM confirmed:
State.OOMKilledistrue, and the event stream includes anoomevent at the same time as thedieevent. - OOM not confirmed:
OOMKilledisfalseand there is nooomevent. Look for akillorstopevent, a manualdocker stopordocker killin your shell history or automation, or a daemon restart at that time.
Build a short lifecycle timeline
Reproduce the crash while an event stream is running, or query a narrow window around the failure:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →docker events --filter 'container=<container>'
docker events --since 10m --filter 'container=<container>'Events of interest include start, die, kill, stop, restart, and oom. Historical queries return at most the most recent 256 events, so collect them soon after the failure. Do not assume that an older event never happened just because it does not appear in a query.
Compare the timestamps with the log lines. A die event that comes right after an application error points at the process. A die event with an oom event before it points at memory. A kill or stop event with no failure in the logs points at something outside the process.
Rank #3
Separate the restart policy from the underlying fault
Docker offers four restart policies. They differ in which exits trigger a restart, whether retries are capped, and how manual stops and daemon restarts are treated.
| Policy | Restarts the container when | Practical note |
|---|---|---|
no (default) |
Never | The container stays exited until you start it again |
on-failure[:max-retries] |
The process exits with a nonzero status | The only policy that accepts a retry cap, which keeps a broken container from looping indefinitely |
always |
Any exit, and again when the Docker daemon starts | Keeps restarting even after a deliberate stop unless the container is stopped and the daemon is also stopped, so it can resurrect a container you meant to keep down |
unless-stopped |
Any exit, except after you stopped the container manually | Behaves like always for crashes, but respects a manual stop |
Docker documents a 10-second threshold for a successful start. Containers that exit before that point are the ones that produce tight crash loops, and Docker spaces their restarts out with a backoff schedule. Treat that spacing as normal engine behavior, not as evidence of a fault.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWhile diagnosing, a bounded policy makes the pattern easier to see because the loop ends on its own. You can change the policy on an existing container without recreating it:
docker update --restart=on-failure:5 <container>Choose the production policy afterwards, based on what the workload should do. A restart policy never repairs a bad command, missing configuration, application bug, or resource shortage; it only changes how often Docker tries again.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Check memory and host limits
On Linux, when the host runs out of memory, the kernel’s OOM killer can terminate container processes and, in some cases, other processes, including Docker or host services. Compare the container’s configured limits with what the host actually has:
docker inspect --format 'memory={{.HostConfig.Memory}} swap={{.HostConfig.MemorySwap}}' <container>Values are in bytes, and a value of 0 means no limit was set. Check the host’s free memory at the time of the failure, since a limit that looks reasonable can still be too low for the workload.
Best Value
- Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
- Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
Disabling the OOM killer with --oom-kill-disable is not a general fix. Without a memory limit, it can leave the host to reclaim memory by terminating other processes. Fix the limit or the workload’s memory use first.
Escalate to daemon logs when the container shows nothing useful
If the container’s output is empty, or it shows no engine-level failure, inspect the Docker daemon’s own logs. Where they live depends on the host platform:
- Linux with systemd:
journalctl -u docker.service - Older Linux setups: some distributions write daemon logs to alternate files. Check the official daemon-logging guide for your platform.
- Docker Desktop on macOS and Windows with WSL2: daemon and related service logs are written to
init.log. - Windows container hosts: the Windows Event Log.
Paths and mechanisms change between releases, so confirm them against the current Docker documentation for your platform before relying on them in a runbook.
Decision branches after the evidence is collected
- Exit 125, 126, or 127: fix the command, entrypoint, executable permissions, or Docker run options, then recreate the container.
- Application error in the logs with a nonzero code: fix the application or its configuration. The restart policy is not the place to fix it.
- OOM confirmed: adjust the memory limit or reduce the workload’s memory use, and confirm the host has enough free memory.
- No container evidence and a kill or stop event from outside the process: find what sent the signal, including scripts, orchestrators, and daemon restarts, and read the daemon logs for the same window.
Once the cause is fixed, restore the restart policy you actually want, and confirm the container stays up past the 10-second threshold.
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.
