Container keeps restarting: restart policy loop
A restart policy restarts a container that exits, so a crashing app loops forever. Read the exit code and logs, then fix the app and limit the retries.
What you see
docker psshowsRestarting (1) 5 seconds ago- A container's uptime keeps resetting
What it means
A restart policy tells the daemon what to do when a container exits. always restarts it whatever the reason, on-failure[:max-retries] restarts only on a non-zero exit, and unless-stopped is like always but stays stopped after you stop it.
The policy only applies once a container has been up for at least 10 seconds, so a container that fails to start at all does not loop. A crash after that point does.
How to confirm the cause
- 1See the exit code and how many times it restarted
docker inspect --format 'restarts={{.RestartCount}} exit={{.State.ExitCode}} policy={{.HostConfig.RestartPolicy.Name}}' CONTAINER - 2Read the logs of the last run
docker logs --tail 100 CONTAINER
The cause of the crash is almost always at the end of the previous run's log.
Causes and fixes
The app crashes after starting
- HOW TO TELL
- A non-zero exit code and an error in the log.
- ROOT CAUSE
- The policy faithfully restarts a program that keeps failing. The loop is a symptom; the crash is the cause.
- FIX
- Fix the app error shown in the log (missing config, bad connection string, failed dependency). Use the exit-code runbook to read the code.
The app exits normally but the policy is always
- HOW TO TELL
- Exit code 0 and it restarts anyway.
- ROOT CAUSE
alwaysrestarts the container even after a successful exit, which is wrong for a one-shot job.- FIX
- Use
on-failureor no policy for jobs. Run long-lived services as long-lived processes.
on-failure with no retry limit
- HOW TO TELL
- A failing container restarts without end.
- ROOT CAUSE
- Without
:max-retriesthe daemon never gives up. - FIX
- Set a limit so a persistent failure becomes visible.
docker update --restart on-failure:5 CONTAINER
How to stop it coming back
- Alert on restart counts.
- Cap retries so a broken release fails loudly.
- Make the app log the reason before it exits.
Keep going
- Runbook: docker run exit codes 125, 126, 127 and 137: what each one means
- Runbook: Container marked unhealthy: HEALTHCHECK failing
- Cheat sheet: Docker
- Lesson: the containers topic in Learn
Sources
Docker documentation (docs.docker.com), read 18 Nov 2026 from the official docs repository.