Quick answer
When a Docker container exits immediately, first check `docker logs` and the exit code. The most common causes are a wrong start command, an application that finishes right away, missing configuration or permissions, and a container with nothing to do in the foreground. Fix the command or entrypoint and run the container interactively to see the error.
How to recognize the problem
- `docker ps` does not show the container, but `docker ps -a` lists it as Exited
- The container starts and disappears within seconds
- Logs are empty or contain only a startup error message
- The application works locally but exits immediately in the container
- Exit code is 0, 1, 127 or 137
Most common causes
Wrong start command or entrypoint
If the Dockerfile or `docker run` command specifies a non-existent command, the container exits with code 127. Check that the path to the executable is correct and that the command is in the format Docker expects.
Application finishes immediately
The container lives as long as the main process runs. If the application just does something and finishes, or if it is started in the background, the container will exit. The main process needs to stay in the foreground.
Missing configuration or permission
The application may crash if it lacks environment variables, a configuration file or write permission. Logs then show a startup error, for example that the database is unavailable or that a file does not exist.
Port or resources
If the port is already in use, startup may fail with a message that the port is already allocated. The container may also exit if there is not enough memory or if the process was killed due to limits.
Dependency between services
In a Docker Compose environment, a container may fail to start or exit if a service it depends on is not ready. Check the order and conditions in `depends_on`, and use healthcheck to verify that the dependent service is actually ready.
Step-by-step fix
- 1
Check status and exit code
Run
docker ps -ato see all containers, including stopped ones. Pay attention to the STATUS column and the exit code. Code 0 means the process finished normally, 1 is a general error, 127 is a non-existent command, and 137 indicates a forced stop, often due to memory. - 2
Review the logs
Run
docker logs <name_or_id>. If the container is stopped, add--tail 100to see the last hundred lines. Logs usually contain the exact reason, for example a configuration error or a message that the command was not found. - 3
Run the container interactively
Bypass the start command and enter a shell:
docker run -it --entrypoint /bin/sh <image>. If the image does not havesh, trybash. Inside the container, run the application manually and see the error you otherwise miss. - 4
Check the command and entrypoint
Look at the Dockerfile and the
docker runcommand. Make sureCMDorENTRYPOINTis in the correct format and that the path to the executable exists. If you usedocker compose, check thecommandfield indocker-compose.yml. - 5
Make sure the main process stays in the foreground
The application must not start in the background or finish immediately. If it is a script, add a loop at the end or start a server that listens. For containers that just need to stay active, use
tail -f /dev/nullas a temporary workaround. - 6
Check environment variables and configuration
Compare
docker inspect <container>with what the application expects. Add missing variables via-eor in theenvironmentsection. Also check that configuration files are mounted at the correct path. - 7
Check permissions and ownership
If the application writes to a volume or folder, make sure the user inside the container has permission. Add
--usertodocker runor adjust the Dockerfile. Permission errors often appear in logs asPermission denied. - 8
Disable healthcheck and dependencies
If you use Compose, temporarily comment out
healthcheckanddepends_onto see if the container works on its own. Then bring them back one by one and observe the behavior. - 9
Rebuild the image
If you changed the Dockerfile, run
docker build --no-cache -t <name> .and then start the container again. A cached layer can hide a change that is causing the problem.
If nothing helps
Enable more detailed application logging and run it with docker run without -d to see the output live. Check whether the container is exiting due to OOMKilled in docker inspect (field State.OOMKilled). If you use Kubernetes or another orchestrator, look at events and restart count. When the problem is in the application itself, run it outside the container with the same environment variables to isolate Docker. For complex cases with multiple services, it is useful to create a minimal docker-compose.yml with only one service and gradually add the others.
How to prevent it
- Always use `docker logs` and the exit code before changing anything.
- Explicitly specify `CMD` or `ENTRYPOINT` in the Dockerfile and test it locally.
- Occasionally clean up stopped containers, unused networks and dangling images with `docker system prune`; before running, check what will be removed and back up important data.
- In the Compose file, define healthcheck and `restart: unless-stopped` for services that should run continuously.
When to call a professional
If you have tried all the steps and the container still exits without a clear reason, or if the problem involves multiple services and a production environment, contact IT support to analyze the configuration and logs together.
Software and product development · Custom apps, SaaS and an MVP in 4 to 8 weeksFAQ
Why does the container exit with exit code 0?
Exit code 0 means the main process finished successfully, but it also means the container has nothing left to do. Most often the application was started in the background or finished immediately. The solution is to keep the main process in the foreground.
How can I see an error that does not appear in the logs?
Run the container interactively with `docker run -it --entrypoint /bin/sh <image>` and run the application manually. That way you will see the output live. You can also temporarily run the container with `sleep 3600` as the command, with `--entrypoint` if needed, then enter it and test.
What does exit code 137 mean?
Code 137 usually means the process was forcibly terminated, most often due to lack of memory (OOM). Check `docker inspect` and the `State.OOMKilled` field. Increase memory or optimize the application.