Why Does a Docker Container Stop Immediately?

To start a Docker container, preliminary results seem to be promising; however, once we try to verify it with docker ps, we can see that it is already terminated. Once you wonder, “Why Does My Docker Container Stop Immediately?”, the basic answer is that a Docker container works as long as its main process is alive.

Luckily, there are several ways of debugging to find out what caused the problem.

Understand Why the Container Stopped

A Docker container is not a regular virtual machine that “runs” without processes. Instead, its lifecycle depends on the main process, which is called PID 1.

Think about the following command:

docker run ubuntu

What do we expect to see for the container like that? Of course, we can assume that an environment with the installed Ubuntu will be created, but there is no process to run in this case.

And now think about the following command:

docker run nginx

In this case, the web server process starts, and thus our container is running.

When a container stops immediately, our first task is to find out the destiny of the main process.

Find Your Stopped Container

The docker ps command lists the running containers:

docker ps

And the following command lists all the containers, even those that are finished:

docker ps -a

The STATUS field gives us the clue to the problem. The output can look like:

Exited (0) 10 seconds ago

Here, 0 means that the process is normally terminated. Any other number denotes the error or abnormal termination.

In case your container is not in the list, check whether you are using the –rm flag with docker run. Such containers are automatically deleted when they exit.

docker run --rm <image>

Get Container Logs

The very first thing that you should do here is:

docker logs <container-name>

The logs show the crashes of the application, its configuration problems, connection problems, permission problems, etc. They can show that you cannot connect to the database or you have missed some important environment variables.

And if you want to check the last 50 lines of logs, you can run:

docker logs --tail 50 <container-name>

The logs give us the quickest way to find out the reasons for the container’s immediate termination.

Check the Exit Status

It is possible to get the exit status of the container from Docker in the following way:

docker inspect <container-name> --format='{{.State.ExitCode}}'

The exit code gives us some hints about what happened with the process. Zero code means that the process was terminated normally; non-zero codes (1) indicate application errors. One of the popular exit codes is 137, it means that the process was terminated with the SIGKILL signal, probably due to an out-of-memory situation.

Instead of interpreting the exit code independently, it is better to combine it with the logs and container inspection results.

Examine the Dockerfile CMD and ENTRYPOINT

For local images, you need to examine the CMD and ENTRYPOINT directives in the Dockerfile, for example:

CMD ["dotnet", "MyApplication.dll"]

Docker assumes that this process will work in the foreground. When the application finishes its job, the container will also finish. The common mistake is starting the application in the background. Docker requires that the main application process runs in the foreground. Also, make sure that your command is correct and the executable or script is present in your image.

Verify Environment Variables and Configuration

A lot of applications require configuration settings passed as part of container startup. For example:

docker run -e CONNECTION_STRING="..." myapp

When some of these variables are missing or incorrectly set, the application will stop immediately. You should check your docker run command, Docker Compose file, .env file, secrets, mounts, and application configuration files. To check the container’s configuration, you can run:

docker inspect <container-name>

This command gives you detailed information about the container.

Debug in an Interactive Shell

One of the simplest ways of debugging an image is to run it interactively. Start the container with the interactive shell:

docker run -it --entrypoint /bin/sh myimage

This environment allows you to check whether the file exists, check environment variables and permissions, and manually start the application that normally starts the application. However, not all images have /bin/sh.

As a rule, containers that stop immediately fail not due to some problems with Docker but because Docker behaves normally by stopping the container when the main process ends.

Understanding this basic idea makes understanding the problems much easier.

Learn Docker Through Your First Substantial Project

Are you ready to gain skills in creating, running, and troubleshooting Docker containers?

Take the course “Docker: Your First Project” in LinkedIn Learning, which is included in the Docker Foundations Professional Certificate Learning Path.

This course gives you knowledge of Docker principles and experience in container creation.