Introduction

Docker restart policies help recover from container exits, but they are not magic high-availability logic. A container may fail and still not restart if no restart policy was set, the chosen policy does not cover that exit path, or the container was stopped manually in a way that suppresses restart. The key is to understand which failure paths your policy actually covers.

Symptoms

  • A container exits and stays down even though operators expected it to restart
  • docker ps -a shows the container exited with no follow-up restart attempts
  • The configured policy behaves differently after manual stops, daemon restarts, or repeated failures
  • Restart count and event history do not match operator expectations

Common Causes

  • No restart policy was configured at all
  • The policy chosen does not match the actual failure mode
  • The container was manually stopped and is therefore treated differently
  • Operators expect restart behavior that belongs in an orchestrator rather than plain Docker

Step-by-Step Fix

  1. 1.Inspect the current restart policy
  2. 2.Confirm the policy name and retry count before assuming Docker is ignoring your configuration.
bash
docker inspect my-container --format "{{.HostConfig.RestartPolicy.Name}}:{{.HostConfig.RestartPolicy.MaximumRetryCount}}"
  1. 1.Check how the container actually exited
  2. 2.Exit codes, error text, and event history help determine whether the restart path should have triggered.
bash
docker inspect my-container --format "{{.State.ExitCode}}"
docker logs --tail 50 my-container
  1. 1.Set or update the restart policy intentionally
  2. 2.Pick on-failure, always, or unless-stopped based on the behavior you actually want.
bash
docker update --restart=on-failure:5 my-container
  1. 1.Retest with a real failure, not a manual stop
  2. 2.Manual lifecycle actions can produce different results than crash-based exits, so verify the scenario you actually care about.

Prevention

  • Set restart policy explicitly on production containers
  • Match the policy to the service’s real recovery expectations
  • Monitor restart counts and exit reasons instead of assuming recovery is happening
  • Use a higher-level orchestrator when restart semantics need to be more sophisticated than Docker alone