🚨 Docker Error Guide: 'Container is restarting, wait until the container is running' — Fix Crash Loops

Overview

Docker returns this when you try to exec into (or otherwise operate on) a container that is caught in a restart loop:

Error response from daemon: Container 7d2e4a91c3f0 is restarting, wait until the container is running

The container has a restart policy (always, unless-stopped, or on-failure), its main process keeps exiting, and the daemon keeps relaunching it. Between attempts the container is in the restarting state, and you cannot exec into a process that is repeatedly dying. The message is a symptom of a crash loop.

Symptoms

• docker exec fails with is restarting, wait until the container is running.
• docker ps shows the status flickering — Restarting (1) 3 seconds ago — and the uptime never grows.
• The RestartCount in docker inspect climbs steadily.
• A Compose service with restart: always never becomes healthy.

Common Root Causes

• The application crashes on startup and a restart policy relaunches it endlessly — a bad config, missing dependency, or failed migration.
• A dependency is not ready — the app exits because a database or upstream service it needs is not reachable yet.
• Non-zero exit combined with restart: always — any failure is retried forever instead of surfacing.
• Failed healthcheck causing external restarts — an orchestrator kills and recreates the container repeatedly.
• Resource limits too low — the process is OOM-killed shortly after start on each attempt.
• Bad entrypoint or command that exits immediately, retried by the policy.

Diagnostic Workflow

Confirm the state, restart policy, and how many times it has restarted:

docker ps --filter "id=7d2e4a91c3f0"
docker inspect --format 'status={{.State.Status}} restarts={{.RestartCount}} policy={{.HostConfig.RestartPolicy.Name}}' 7d2e4a91c3f0

Read logs across restarts — the loop reason repeats every cycle:

docker logs --tail 40 --timestamps 7d2e4a91c3f0

Check the exit code and whether the kernel is killing it:

docker inspect --format 'exit={{.State.ExitCode}} oom={{.State.OOMKilled}}' 7d2e4a91c3f0

To break the loop so you can investigate calmly, stop the container (which disables further restarts until you start it) and relaunch with the policy off and the failing entrypoint replaced:

docker stop 7d2e4a91c3f0
docker run -it --rm --restart no --entrypoint sh myapp:1.4.2

For daemon-level clues on repeated kills:

journalctl -u docker --since '10 min ago' | grep -i '7d2e4a91c3f0\|oom'

Example Root Cause Analysis

A payments worker deployed with restart: always never stabilized. docker ps cycled through Restarting (1) and docker exec returned is restarting, wait until the container is running.

Inspecting showed a fast-growing restart count and a clean exit code of 1 (not an OOM):

docker inspect --format '{{.RestartCount}} {{.State.ExitCode}} {{.State.OOMKilled}}' worker
# 47 1 false

The logs, read across cycles, repeated the same line:

docker logs --tail 5 worker
# FATAL: could not connect to database "orders" at db.example.com:5432

The worker started before its database dependency and exited; the restart policy then hammered it. The fix was twofold: add a startup wait/retry with backoff inside the app so a not-yet-ready database no longer causes an immediate exit, and use restart: on-failure:5 instead of always so a genuine misconfiguration surfaces after a bounded number of attempts rather than looping forever.

Prevention Best Practices

• Prefer on-failure:<n> over always for services that can fail permanently, so a broken build stops looping and becomes visible.
• Implement dependency waits with backoff (or depends_on with healthchecks in Compose) instead of exiting when an upstream is not ready.
• Add a HEALTHCHECK and monitor RestartCount so crash loops trigger alerts early.
• Set realistic memory limits and watch for OOMKilled on restart.
• Validate startup configuration and the entrypoint with the Dockerfile validator, and standardize runtime policies from the Docker stack guide.

Quick Command Reference

docker ps --filter "id=<id>"
docker inspect --format '{{.State.Status}} {{.RestartCount}} {{.HostConfig.RestartPolicy.Name}}' <id>
docker logs --tail 40 --timestamps <id>
docker inspect --format '{{.State.ExitCode}} {{.State.OOMKilled}}' <id>
docker stop <id>                                       # halts the restart loop
docker run -it --rm --restart no --entrypoint sh myapp:1.4.2   # debug calmly

Conclusion

This message means a restart policy is fighting a process that keeps dying. You cannot exec into a container that is mid-restart, so stop chasing the exec error and diagnose the loop: check RestartCount, read docker logs across cycles, and confirm the exit code and OOM status. Stop the container to freeze the loop, reproduce with --restart no, and fix the underlying crash — usually a missing dependency, bad config, or resource limit — before restoring the policy.