Skip to content
statance
MenuClose
← All troubleshooting guides

A Docker container keeps restarting

Linux

Check the exit code and OOM flag with docker inspect, then read the last logs with docker logs --tail 100. Exit code 137 with OOMKilled true means it ran out of memory; exit code 1 is usually an application error such as missing configuration; 127 means the command was not found.

Symptoms

  • docker ps shows “Restarting (1) 5 seconds ago”
  • The container’s restart count keeps rising
  • The service is reachable only briefly

How to diagnose it

  1. Check status and restart count

    Shows exit code, restart count and whether it was OOM-killed.

    docker ps -a docker inspect -f '{{.State.ExitCode}} {{.State.OOMKilled}} {{.RestartCount}} {{.State.Error}}' CONTAINER
  2. Read the logs

    Logs include output from previous attempts.

    docker logs --tail 100 CONTAINER
  3. Check the health check

    An unhealthy container restarted by an orchestrator shows its probe output here.

    docker inspect -f '{{json .State.Health}}' CONTAINER
  4. Run it interactively

    Override the entrypoint to look inside.

    docker run --rm -it --entrypoint sh IMAGE

Common causes and fixes

Out of memory (exit code 137, OOMKilled true)

Raise the memory limit or reduce memory use.

docker update --memory 1g --memory-swap 1g CONTAINER

Application error on start (exit code 1)

Usually missing environment variables, a wrong config path or an unreachable database. The logs say which.

Command not found (127) or not executable (126)

Fix the CMD or ENTRYPOINT path, the shell in the image, or file permissions.

Process exits immediately because it daemonises

Containers stop when PID 1 exits. Run the service in the foreground (e.g. nginx -g "daemon off;").

Dependency not ready

Add retries in the app, or depends_on with condition: service_healthy in Compose.

Prevent it happening again

  • Statance reports each container’s status, CPU, memory and network so restarts and memory growth are visible.
  • Add an HTTP or TCP check on the container’s published port to alert when it is down.

Set it up: Docker monitoring · Kubernetes monitoring.

FAQ

What does exit code 137 mean in Docker?

The process was killed with SIGKILL (128 + 9), usually by the OOM killer or docker kill.

How do I stop a container from restarting?

docker update --restart=no CONTAINER, then docker stop CONTAINER.

Related guides

Get alerted before this becomes an outage.

Install the agent in one line. Statance watches CPU, memory, disk and services, and its AI assistant helps find the cause.