Docker container restart loop

Inspect container status, logs, restart policy, exit code, and recent events before rebuilding or deleting containers.

Safest first command

docker ps -a --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.RestartCount}}'

Before you run this

Expected output: A table showing container names, images, status strings, and restart counts.

When not to use it: Do not delete containers, images, or volumes before reading logs and restart policy.

Expected output example

NAMES     IMAGE        STATUS                         RESTARTS
api       app:latest   Restarting (1) 12 seconds ago  14
worker    app:latest   Up 2 hours                     0

How to read the result

A rising restart count means Docker is repeatedly starting a process that exits or fails health checks. Logs and exit code are the next evidence.

What to check next

Restarting with high count

Means: The process exits quickly or the restart policy keeps reviving it.

Next step: Read recent logs for that container.

Read Recent Docker Container Logs

Exited with non-zero code

Means: The application stopped and Docker may be following policy.

Next step: Inspect restart policy and exit code.

Inspect Docker Restart Policy

Events show repeated die/start

Means: The loop timing can identify deployment or dependency changes.

Next step: Read recent Docker events.

Read Recent Docker Restart Events

Restart-loop decision tree

Find the container, read its logs, inspect the exit code and restart policy, then decide whether the problem is app config, dependency, image, or environment.

docker ps -a --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.RestartCount}}'
docker logs --tail 80 container_name
docker inspect -f '{{.HostConfig.RestartPolicy.Name}} {{.State.ExitCode}} {{.State.Error}}' container_name
docker events --since 30m --until 0s

Bad fixes to avoid

Do not prune volumes, rebuild images, or delete containers before proving where persistent data lives and why the process exits.

Common causes

Bad environment variable or missing secret.
Dependency unavailable at startup.
Wrong command or entrypoint.
Health check failure mistaken for process crash.

What not to change yet

Do not run docker system prune.
Do not remove volumes.
Do not disable restart policy until you capture logs.

Stop and escalate if

The next step could interrupt users, remove data, or lock out access.
The output includes secrets, customer data, or private infrastructure details.
You cannot explain the blast radius of the repair command.

supporting commands