Docker Container Keeps Restarting: How to Fix It

What you're seeing

$ docker ps
CONTAINER ID   IMAGE         STATUS                          NAMES
abc123def456   myapp:latest  Restarting (1) 3 seconds ago    myapp

Or from docker ps -a:

CONTAINER ID   STATUS                              NAMES
abc123def456   Restarting (137) 15 seconds ago     myapp

The number in parens is the exit code, the single most useful piece of information on the screen.

What's causing this error

A container restarts when:

1. Its main process exits, and
2. The container has --restart always, --restart on-failure, or --restart unless-stopped

So "container keeps restarting" really means "the process inside the container keeps exiting." The five real reasons:

1. App crashes immediately on startup. Missing config, bad env var, syntax error, missing file. The logs almost always say why. Most people just don't check them.
2. App exits cleanly (exit 0). Some images run a one-shot command and exit. With --restart always, Docker dutifully restarts the now-completed task forever.
3. OOM killed. The container exceeds its memory limit. Linux's OOM killer sends SIGKILL → exit 137.
4. Missing dependency at runtime. A volume isn't mounted, a network service isn't reachable, a config file isn't where the app expects.
5. Healthcheck failing. With Swarm or compose restart: on-failure policies, failing healthchecks trigger restarts even when the process itself is alive.

How to fix it

Step 1: Read the logs

docker logs --tail 100 myapp

90% of the time this prints the actual error. Look for stack traces, "permission denied," "connection refused," "no such file or directory," "ENOENT," panic messages.

If logs are empty or <no log>, the process didn't get far enough to write anything, which usually means the entrypoint script is broken or the binary doesn't exist.

Step 2: Check the exit code

docker inspect myapp --format='{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}'

What the common exit codes mean:

Step 3: Stop the restart loop while you debug

The loop makes diagnosis hell. The container disappears between every docker exec. Disable restart:

docker update --restart=no myapp
docker stop myapp

Now you can run it interactively to see what happens:

docker run --rm -it --entrypoint sh myapp:latest
# Inside the container, manually run whatever the CMD was:
# /app/start.sh

This gives you a shell, runs the failing command, and shows you the actual output.

Step 4: Fix by category

Exit 0 + --restart always means the app is finishing its work and Docker restarts it forever:

docker update --restart=on-failure myapp
# Or remove the restart policy entirely:
docker update --restart=no myapp

on-failure only restarts on non-zero exits, leaving clean exits alone.

Exit 137 + OOMKilled: true means the memory limit is too low:

docker update --memory=1g --memory-swap=1g myapp

Or remove the limit if you set one too aggressively:

docker update --memory=0 myapp

Exit 127 (command not found): your CMD references a binary that isn't in the image. Usually a copy/paste error in the Dockerfile or wrong path. Run interactively (step 3) and check which <command>.

Healthcheck failing happens when the process is fine but the healthcheck script is wrong. Check:

docker inspect myapp --format='{{json .State.Health}}' | jq

Either fix the healthcheck command in your Dockerfile, or remove it temporarily:

# docker-compose.yml
services:
  myapp:
    healthcheck:
      disable: true

Common edge cases