A Docker container keeps restarting and never stays up
docker ps shows an uptime of a few seconds that never growsShort 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.
Fix it fast
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>2Match what you see, then jump to its fix
- 1
docker logs ends with a stack trace or a missing variable or fileThe app crashes at startFix - 2
Exit code 0 and a log that shows the command ran, then nothingThe main process finishes by design or leaves the foregroundFix - 3
docker inspect shows always or unless-stopped, and the container never reaches a stable stateA restart policy keeps a broken container aliveFix
- 1
What does the error look like?
docker ps shows an uptime of a few seconds that never growsdocker 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
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-appConfirmed by pm2.keymetrics.io
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
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
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fixServers
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