Back to Articles
Docker7 min read
Docker Container Keeps Restarting? Fix It in 5 Minutes
Is your Docker container stuck in a crash loop? Learn how to diagnose exit codes, check logs, and fix restarting containers fast.
Is your Docker container stuck in a crash loop? Learn how to diagnose exit codes, check logs, and fix restarting containers fast.
You deployed a Docker container, checked the logs, and everything looked fine — but five minutes later, the container is down again. Then it's back up. Then down. This crash loop is one of the most frustrating issues you will encounter when running Docker in your homelab, whether you are self-hosting a media server, a database, or a custom web application.
The good news? Most restart loops have a small handful of common causes, and you can diagnose them in under five minutes using built-in Docker commands. This guide walks you through the exact steps to stop the loop, find the root cause, and apply a lasting fix.
A container enters a restart loop when its main process exits unexpectedly and the container's restart policy tells Docker to bring it back up. If the process keeps failing on each attempt, the container cycles endlessly between starting and crashing.
The most common causes include:
Before you can investigate, you need to break the cycle. Use docker update to temporarily disable the restart policy on the affected container.
docker update --restart no your-container-nameNote: This command changes the restart policy to no, which means the container will not restart after it stops. It will exit on the next stop and stay stopped, giving you time to investigate without the loop interfering.Once you have resolved the underlying issue, you can re-enable the restart policy:
docker update --restart unless-stopped your-container-nameDocker stores detailed information about every container's last run. Use docker inspect to see the exit code, restart count, and whether the container was killed by the OOM killer.
docker inspect your-container-name --format='
Status: {{.State.Status}}
RestartCount: {{.State.RestartCount}}
ExitCode: {{.State.ExitCode}}
OOMKilled: {{.State.OOMKilled}}
StartedAt: {{.State.StartedAt}}
FinishedAt: {{.State.FinishedAt}}
'Interpret the exit codes:
If OOMKilled is true, the container was terminated because it ran out of allocated memory.
The container logs are your best friend for diagnosing why the application is crashing.
docker logs your-container-name --tail 100To follow log output in real time across restart cycles:
docker logs your-container-name -fLook for error messages, stack traces, or missing file warnings near the end of the output. Common log patterns include:
If the container is being killed by the OOM killer (exit code 137, OOMKilled: true), you need to check its memory usage.
docker stats your-container-name --no-streamLook at the MEM USAGE and MEM LIMIT columns. If usage hits the limit, the kernel kills the process. You can resolve this by:
docker run command using --memory.If OOMKilled is false but the exit code is still 137, the process may have been killed by the host's OOM killer at the system level, or by a manual kill command.
Sometimes the logs are not enough. You can run the same image interactively to reproduce the crash manually.
docker run --rm -it \
--env-file .env \
your-image-name /bin/shOnce inside the shell, try running the entrypoint command manually. For example:
ls -la /app/Check if the expected files exist and if the startup script is executable:
test -x /app/start.sh && echo 'executable'This approach lets you see exactly what happens when the application starts, without the restart cycle getting in the way.
Fix: Look at the logs and fix the application configuration. Common fixes include correcting environment variable names, mounting missing volumes, or updating the command in your Dockerfile.
Fix: Verify the CMD and ENTRYPOINT instructions in the Dockerfile. Run the image interactively and test the command manually. Update your Dockerfile or override the command in docker-compose.yml.
Fix: Ensure all required files, environment variables, and volumes are present. Check that mounted host paths exist and have the correct permissions.
Fix: Increase the memory limit or optimize the application. In docker-compose.yml:
services:
your-service:
mem_limit: 512mOr with docker run:
docker run -d --memory=512m your-imageFix: Change the host port mapping or stop the service using the conflicting port. Check which process is using the port with:
sudo lsof -i :8080Docker provides several restart policies that control what happens when a container exits. The right policy depends on your use case.
on-failure:5.Important: If you manually stop a container using docker stop, the restart policy is ignored until the Docker daemon restarts or the container is manually restarted.Once you have fixed the immediate issue, take these steps to prevent it from happening again:
docker logs --tail --follow or a centralized logging stack.A Docker container that keeps restarting can feel like a mystery, but it is almost always solvable with a systematic approach. Stop the loop with docker update --restart no, inspect the exit code with docker inspect, read the logs with docker logs, and check memory with docker stats. In most cases, the root cause is one of a handful of common issues — a missing file, a port conflict, an OOM kill, or a misconfigured command.
With these five steps, you can diagnose and fix a restarting Docker container in under five minutes and get back to running your homelab services without the crash loop headache.