DockerMid

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 ps shows Restarting (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

  1. 1
    See the exit code and how many times it restarted
    docker inspect --format 'restarts={{.RestartCount}} exit={{.State.ExitCode}} policy={{.HostConfig.RestartPolicy.Name}}' CONTAINER
  2. 2
    Read 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
    always restarts the container even after a successful exit, which is wrong for a one-shot job.
    FIX
    Use on-failure or 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-retries the 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

Sources

Docker documentation (docs.docker.com), read 18 Nov 2026 from the official docs repository.

Search

Search cheat sheets and projects