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 — it's 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 — 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 — 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 — memory limit 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 — 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