Why Does My Docker Container Stop? (2023)

After a container finishes executing its default command, it will stop.

Written byTom DonohueWhy Does My Docker Container Stop? (1)

Updated: 19 April 2022


When you run a container image you’ve pulled from a registry like Docker Hub, you’re launching a process. This process will, eventually, complete. That means that, sooner or later, your Docker container will come to a complete stop, whether by choice or accident.

A Docker container exiting doesn’t usually indicate that something is wrong. But, nevertheless, you might be wondering why it’s exited!

This is especially the case if you’re using Kubernetes, which will restart failed containers, and give you that dreaded CrashLoopBackOff error.

To understand why containers exit, it’s really helpful to understand the difference between containers and VMs.

Containers are not like virtual machines.

You probably know that VMs are like virtual computers that keep running until you tell them to stop.

But containers don’t run an entire operating system. They only run (contain) a specific process. When this process finishes, the container exits.

(Video) Restart Stopped Containers (Restart Policies) - Docker Development Tips & Tricks

So why does a container stop?

The lifecycle of a container

To understand why and when a container stops, we need to look at the lifecycle of a container. A Docker container goes through various stages of life - like a bee 🐝.

Why Does My Docker Container Stop? (2)

A container is simply an isolated process running on your computer. A Docker container can be in one of several core states:

  • Created - The Docker container has been created, but not started (e.g. after using docker create)

  • Up - The Docker container is currently running. That is, the process inside the container is running. Can happen using docker start or docker run.

  • Paused - The Docker container has been paused, usually with the command docker pause.

  • Exited - The Docker container has exited, usually because the process inside the container has exited.

Why a Docker container terminates

So why does a container terminate, or exit? There are several reasons why a Docker container might end:

  • The main process inside the container has ended successfully: This is the most common reason for a Docker container to stop! When the process running inside your container ends, the container will exit.

    Here are a couple of examples:

    • You run a container, which runs a shell script to perform some tasks. When the shell script completes, the container will exit, because there’s nothing left for the container to run.

      (Video) How to Start and Stop Docker Containers?

    • You run a utility which is packaged as a Docker container, like the Busybox or Maven images. When the utility finishes, the container exits.

  • You’re running a shell in a container, but you haven’t assigned a terminal: If you’re running a container with a shell (like bash) as the default command, then the container will exit immediately if you haven’t attached an interactive terminal. If there’s no terminal attached, then your shell process will exit, and so the container will exit. You can stop this by adding --interactive --tty (or just -it) to your docker run ... command, which will let you type commands into the shell.

  • The process inside the container has been terminated: This is when the program that runs inside the container is given a signal to shut down. This happens if you run a foreground container (using docker run), and then press Ctrl+C when the program is running. When this happens, the program will stop, and the container will exit.

  • The container has been stopped using docker stop: You can manually stop a container using the docker stop command.

  • The Docker daemon has restarted, and it terminated and restarted the container: Docker can restart containers if you need it to. By default, Docker doesn’t automatically restart containers when they exit, or when Docker itself restarts. To configure Docker to restart containers automatically, use a restart policy using the --restart switch, when you run a container using docker run.

  • The container has consumed too much memory, and has been killed by the host OS: If the operating system detects that it’s running out of memory, it might start killing processes to free up memory. If a container is using a lot of memory or resources, it might be killed by the OS. You can set hard memory limits on your container by using the -m switch with docker run.

Why Does My Docker Container Stop? (3)

How to find out why a Docker container exits

If you run a container and it’s terminating unexpectedly, and you’re not sure why, you need to think about what the container is doing when it starts. Is the script that is running inside the container exiting? Is the application crashing?

To find out what’s going on, you need to get more information about the container. You can get this information by looking at a container’s logs and its state.

1. Look at the logs

The best way to explore what goes on inside a Docker container is to look at the logs using docker logs <container_id>:

  • Do the logs show the application starting up properly?

  • Can you see any helpful debug messages from the application?

    (Video) Docker Tutorial - How do I debug a docker container problem? How do I repair a docker container?

  • Does the application crash with a stack trace (e.g. Java) or some other debugging information?

You’ll need to figure out whether the logs give you a clue as to why the process is exiting unexpectedly.

2. Check the state of the container

You can view details about a container by using docker inspect <container_id>. This command shows a lot of information about the container, including its state. The state includes information like the container’s exit code and perhaps the error message that was returned:

"State": { "Status": "exited", "Running": false, "Paused": false, "Restarting": false, "OOMKilled": false, "Dead": false, "Pid": 0, "ExitCode": 0, "Error": "", "StartedAt": "2020-10-30T11:44:56.344308725Z", "FinishedAt": "2020-10-30T11:48:23.434250526Z", "Healthcheck": { "Status": "", "FailingStreak": 0, "Log": null }}

Look at the container’s exit code. In this example, the container’s exit code was 0. An exit code or exit status of 0 generally means that the application successfully completed. But any other exit code indicates an unsuccessful exit. Some exit codes have further, specific meanings, which you might need to check with the person who wrote the program.

If you run a container and it terminates immediately, it is frustrating to figure out what’s going on. But fear not. You can debug this situation by creating a shell in the container, to give you time to run the offending script, and troubleshoot the issue.

To debug this situation and find out why the container is stopping, create and start a container from the same failing image, and override the entrypoint with a shell, like sh or bash. This will start the container, and drop you in to a shell session, where you can run your script, and see whether it is exiting unexpectedly.

Try starting a new container and dropping into a shell

Example: The following command runs the nginx:latest image, but overrides its default entrypoint. The default entrypoint will normally start the nginx web server. But when we run this command, the container starts, and opens a shell, so that you can do some debugging inside the container. Perhaps you would use the shell to run the usual entrypoint startup script, and see what’s happening, or print out some environment variables:

docker run --interactive --tty --entrypoint /bin/sh nginx:latest
(Video) Starting and Stopping Docker Containers - Docker tutorial - docker container tutorial beginners #15

How to prevent a container from stopping

So how do you prevent a container from stopping?

Perhaps you have a script which runs in a container, and it’s terminating too early.

Or maybe you want to run a few commands in a container, and keep it running in the background when you’re not using it. (This isn’t the ideal use for containers, but sometimes it’s useful.)

There are a few ways that you can prevent a container from stopping - all of these are simply ways to keep a process alive:

  • Run a long-lived service inside the container: Most containers run a long-living service, like a database or a web server. These processes keep running until they receive a shutdown signal. This is the usual way that a container runs for an extended period without stopping – because the underlying process keeps running.

  • Add an artificial sleep or pause to the entrypoint: If your container is running a short-lived process, the container will stop when it completes. You can artificially extend this by adding some code to the entrypoint script (if you have one), to wait or sleep for a while. You could tell the script to sleep for a fixed period, or perhaps tell it to sleep indefinitely. For example, in bash, you can use this to create an infinite pause: while true; do sleep 1; done.

  • Change the entrypoint to an interactive shell: This is useful if you want to use a container like a virtual machine, and keep it running in the background when you’re not using it. If you override the entrypoint to the container with a shell, like sh or bash, and run the container with the -itd switches, Docker will run the container, detach it (run it in the background), and attach an interactive terminal. Note that this won’t run the container’s default entrypoint script, but run a shell instead. Effectively, you will have a container that stays running permanently. For example: docker run --entrypoint /bin/sh -itd mycontainer:latest

In the real world

When people use containers in the real world, how do they keep them alive?

Docker containers are used, literally, to contain an existing application. They are a way of putting an application in its own box, so it has limited access to resources. Containers are often used for long-running processes, like web servers or database servers, or for short-lived utilities, like fetching a web site or copying a file.

Containers aren’t usually used like general-purpose virtual machines. They are designed to run, or contain, a single application. This allows them to start up fast, and to exit when no longer needed (which usually happens when the main process inside the container has finished).

However you choose to keep your container alive, remember that Docker containers are at their simplest and most powerful when they are used to contain a single process, from startup to completion.

(Video) How to know the reason why my docker container exits?

Want to learn more? The Containers Fundamentals course will teach you how to install, spin up, manage and troubleshoot containers.


Why does docker container stop? ›

The main process inside the container has ended successfully: This is the most common reason for a Docker container to stop! When the process running inside your container ends, the container will exit. Here are a couple of examples: You run a container, which runs a shell script to perform some tasks.

How do I stop docker containers from stopping? ›

The simplest way to keep the container running is to pass a command that never ends. We can use never-ending commands in any of the following ways: ENTRYPOINT or CMD directive in the Dockerfile. Overriding ENTRYPOINT or CMD in the docker run command.

What happens when docker container stops? ›

docker stop: The main process inside the container will first receive a SIGTERM and, after a grace period, a SIGKILL. docker kill: The main process inside the container will be sent SIGKILL(by default) or any signal specified with –signal.

How do I make sure docker container is always running? ›

Method 1: You can use the -t (pseudo-tty) docker parameter to keep the container running. Method 2: You can run the container directly passing the tail command via arguments as shown below. Method 3: Another method is to execute a sleep command to infinity.

How do I resume a stopped docker container? ›

Enter the docker start command with the Container ID in the command line to resume the Container. Note: This preserves environment variables set during the initial docker run statement.

How do I start a stopped docker container? ›

Container Stop/Restart procedure
  1. To verify if the container has stopped run docker ps -a command. The status of the stopped container would display as Exited . docker ps -a.
  2. Start a Docker container in a stopped state docker start <container_name/id> Connect:Direct service automatically starts inside the container.

How long is docker stopping? ›

By default, the docker stop command gives a grace period of 10 seconds for the running docker container to exit. The docker container is stopped forcefully after the grace period. In the syntax above, you can choose to use –time or -t.

Does restarting docker restart containers? ›

For a major version upgrade, one has to tear down all running containers. With a restart policy of always , however, the containers will be restarted after the docker daemon is restarted after the upgrade.

How to restart docker daemon? ›

  1. Create a systemd drop-in directory for the docker service: $ sudo mkdir -p /etc/systemd/system/docker.service.d.
  2. Flush changes and restart Docker. $ sudo systemctl daemon-reload $ sudo systemctl restart docker.


1. Docker Crash Course #7 - Starting & Stopping Containers
(The Net Ninja)
2. Docker container Commands( pause,unpause,start,stop)| Diff between pause,stop
3. Docker Containers: Remove Docker Containers and Images | Stop Container
4. How To Remove All Stopped Containers And Unused Images In Docker Prune command in docker
(Mukesh otwani)
5. How to Start a Stopped Docker Container
6. Restart stopped containers - learn restarting stopped containers | start, stopped containers #12
Top Articles
Latest Posts
Article information

Author: Francesca Jacobs Ret

Last Updated: 07/14/2023

Views: 6671

Rating: 4.8 / 5 (48 voted)

Reviews: 95% of readers found this page helpful

Author information

Name: Francesca Jacobs Ret

Birthday: 1996-12-09

Address: Apt. 141 1406 Mitch Summit, New Teganshire, UT 82655-0699

Phone: +2296092334654

Job: Technology Architect

Hobby: Snowboarding, Scouting, Foreign language learning, Dowsing, Baton twirling, Sculpting, Cabaret

Introduction: My name is Francesca Jacobs Ret, I am a innocent, super, beautiful, charming, lucky, gentle, clever person who loves writing and wants to share my knowledge and understanding with you.