Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A Docker container keeps restarting and never stays up

Errordocker ps shows an uptime of a few seconds that never grows

Short answer

A container restarts forever when its main process exits and a restart policy starts it again. The policy is not the bug. Read the container's logs to see why the process ended, stop the loop with docker update --restart no, then fix the app, or run a process that stays in the foreground.

  • Applies to Docker Engine 27, Docker Compose 2.3x, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List containers that are in the restarting state, then read the last log lines of one. The log is where the exit reason is.

    docker ps -a --filter status=restarting
    docker logs --tail 50 --timestamps <container>
  2. 2Match what you see, then jump to its fix

    1. 1docker logs ends with a stack trace or a missing variable or fileThe app crashes at startFix
    2. 2Exit code 0 and a log that shows the command ran, then nothingThe main process finishes by design or leaves the foregroundFix
    3. 3docker inspect shows always or unless-stopped, and the container never reaches a stable stateA restart policy keeps a broken container aliveFix

What does the error look like?

  • docker ps shows an uptime of a few seconds that never grows
  • docker ps --filter status=restarting lists the container

Cause 1 of 3

The app crashes at start

1Check

A restart policy only repeats a container that already exited. The log shows what killed the process. Typical causes are a missing environment variable, a wrong database host or a config file that is not mounted.

docker logs --tail 100 <container>
docker inspect --format '{{.State.ExitCode}}' <container>

2Fix

Fix the error in the log, then recreate the container with the right environment and mounts.

docker rm -f <container>
docker run -d --name <container> --env-file .env <image>

3Verify

The container stays up past the first minute.

docker ps --filter name=<container>

Confirmed by docs.docker.com

Did this fix it?

Cause 2 of 3

The main process finishes by design or leaves the foreground

1Check

A container lives only as long as its main process. A one-shot script, or a command that starts a daemon and returns, ends the container at once. PM2 is the usual case in Node.js images: its Docker guide tells you to use pm2-runtime as the command instead of node.

docker inspect --format '{{.Config.Cmd}} {{.Config.Entrypoint}}' <container>

2Fix

Make the command run in the foreground. For a PM2 app, use pm2-runtime in the Dockerfile.

# Dockerfile
CMD ["pm2-runtime", "ecosystem.config.js"]

3Verify

Rebuild and run it. The container no longer exits.

docker build -t my-app .
docker run -d --name my-app my-app
docker ps --filter name=my-app

Confirmed by pm2.keymetrics.io

Did this fix it?

Cause 3 of 3

A restart policy keeps a broken container alive

1Check

With always or unless-stopped, Docker retries without end. The delay between tries starts at 100 ms and doubles up to one minute, so the loop looks calm after a while but never stops.

docker inspect --format '{{.HostConfig.RestartPolicy.Name}}' <container>

2Fix

Turn the policy off while you debug. When the app works again, use on-failure with a retry cap, or unless-stopped.

docker update --restart no <container>
docker stop <container>
# later, once fixed
docker update --restart on-failure:5 <container>

3Verify

The container stays in exited state and you can read its logs.

docker ps -a --filter name=<container>

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Run new images without a restart policy first, add one once the app has stayed up.
  • Give restart policies a cap: on-failure:5 instead of always.
  • Keep the container's main process in the foreground and log to stdout.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Servers

A dev container port does not open in the browser when Docker runs on a remote host

If your application only accepts calls from localhost, it will reject connections from published ports

Three things usually break it: the app listens only on localhost inside the container, so published ports are rejected; you open the container port instead of the mapped localhost port VS Code shows; or you changed appPort or a Compose ports list and did not rebuild.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.