Docker container keeps restarting? How to find out why
A container stuck in "Restarting (1)" crashes as soon as it starts and Docker keeps bringing it back. How to read its logs between restarts, pause the loop to debug it, and fix the usual causes.
· 6 min read · By the Spot Downtime team
docker ps shows Restarting (1) 12 seconds ago, or the container is "Up 3 seconds" every time you look. That's a crash loop: the container's main process exits, its restart policy (always, unless-stopped or on-failure) starts it again, and it exits again. Docker waits longer between each try, doubling from 100 milliseconds up to a minute, so a loop can look like an outage that comes and goes.
The number in brackets is the last exit code. It's the first clue.
1. Read the logs from the last attempt
Logs survive restarts, so the last lines before each crash are there:
docker logs --tail 100 myapp
docker logs --since 10m -f myapp # watch the next attempt liveAnd the facts Docker keeps about the last exit:
docker inspect --format 'exit={{.State.ExitCode}} oom={{.State.OOMKilled}} restarts={{.RestartCount}} error={{.State.Error}}' myappWith the exit code in hand, the exit code guide tells you where to look: 1 is your app, 126 or 127 a broken command, 137 with oom=true memory, 139 a native crash.
2. Stop the loop so you can look
A container that restarts every few seconds is hard to debug. Pause the policy, then start it by hand with a shell instead of the app:
docker update --restart=no myapp
docker stop myapp
# Same image, same settings, but a shell instead of the app
docker run --rm -it --entrypoint sh --env-file .env myimage
# start the app's command by hand and watch the errorWith Compose, docker compose run --rm --entrypoint sh myservice does the same with the service's volumes, network and environment. Put the policy back afterwards with docker update --restart=unless-stopped myapp.
The usual causes
Missing or wrong configuration
An environment variable that isn't set, a secret file that isn't mounted, a config path that changed between image versions. Apps often check these at startup and exit with 1. Compare docker inspect --format '{{.Config.Env}}' myapp with what the app expects.
A dependency that isn't ready
The app starts before its database, cache or queue accepts connections, fails, and exits. depends_on in Compose only waits for the other container to start, not to be ready. Use depends_on with condition: service_healthy and a health check on the database, or make the app retry its first connection.
Out of memory
If OOMKilled is true, the container dies every time it reaches its memory limit, often during startup when caches warm up. Raise the limit or tune the runtime's heap size; see out-of-memory kills.
The process goes to the background
If the exit code is 0, the main process finished. A service that daemonizes itself, or a script that starts the app with & and ends, leaves the container nothing to run. Run it in the foreground.
A failing health check with an orchestrator
Plain Docker only marks a container unhealthy; it doesn't restart it. Swarm, Kubernetes and tools like autoheal do. If the logs show the app running happily until it's killed with 137 or 143, the health check is the problem: see unhealthy containers.
Permissions on a mounted volume
An image that runs as a non-root user can't write to a host directory owned by root. The log says permission denied or EACCES. Set the directory's owner to the container user's UID (sudo chown -R 1000:1000 ./data), or use a named volume.
The port is taken inside the container
address already in use from inside the container usually means two processes in it want the same port, or the app was started twice by an entrypoint script.
Don't restart forever
on-failure:5 stops after five failed attempts, so a broken deploy shows up as a stopped container instead of a loop that hides the problem and fills the logs.Get alerted on the first crash, not the hundredth
- Install the Spot Downtime agent with
--docker(see the server agent). - The server then alerts when a container keeps restarting, or when it crashed and was restarted since the last minute's report, even when the restart policy brought it back.
- For a container that matters most, click Monitor in the server's Containers table: it becomes its own monitor with uptime, incidents and text or call alerts.
- The server's container alerts wait until the container has run normally for two minutes before saying it recovered, so a loop doesn't send a message every minute.
Get new guides by email
Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.
Keep reading
- Docker · Servers · TroubleshootingPermission denied on /var/run/docker.sock: the safe fix"Got permission denied while trying to connect to the Docker daemon socket" means your user can't use Docker's socket. How to fix it with the docker group, why chmod 666 is a bad idea, and what to do for monitoring agents, CI runners and WSL.November 5, 2026 · 5 min read
- Docker · Servers · TroubleshootingDocker exit codes explained: 0, 1, 125, 126, 127, 137, 139 and 143What each Docker container exit code means, how to tell a crash from a clean stop, why 137 is either out of memory or docker stop, and the commands that show what happened.November 5, 2026 · 6 min read