Find out Why Your Docker Container Keeps Crashing

You have been struggling for ages. Rebuilding without caching, adding lines to your Dockerfile, disabling non-vital parts just to make it work.

Still, the exit code you keep seeing is 1. And there’s no useful output in the terminal.

How close are you to stripping the Dockerfile back to Alpine and starting over?

The following workflow which will help you figure out why your container won’t start. Without starting over, or making big changes.

If you’re working with docker-compose or Docker stack, check out this article first.

The Exit Code

If you haven’t checked it yet, this might be a first hint. You can either try to run your container without the -d flag, or check the exit code of a stopped container with

$ docker ps -a

and finding the most recent one in the output.

Depending on the exit code, you might have something useful to work with.

Nope, The Exit Code is not Useful

So it’s the good ol’ exit with code 1. Or another equally useless number.

First, you’ll have the best experience if bash is available in your image. You can add something like the following line to your Dockerfile for now:

# If you are using Alpine:
RUN apk add --no-cache bash coreutils grep sed

The most important part is bash. The best way to debug a solo crashing container is to get interactive. (You could use sh here, but that’s a bit uncomfortable at times).

Getting Interactive

We want to run a container which does not stop and go away. We want to take our time, run commands and look around.

Your image is probably configured to directly run your app of choice inside of the container. Let’s change that and run bash instead.

Instead of changing the Dockerfile, commenting out lines and rebuilding, you can override both the CMD and ENTRYPOINT commands. Here’s an example command:

$ docker run -it --entrypoint /bin/bash $IMAGE_NAME -s

The positioning is quite important. Make sure to replace the $IMAGE_NAME with your image ID or the name of the image you’re working with.

The –entrypoint parameter makes the container execute /bin/bash, which gets “-s” as CMD, overwriting anything the image might otherwise insist on.

Time to Investigate

Now, you have an interactive bash environment, and can look around without getting kicked out. Try to run the command your container is supposed to be running in the bash. Is there an output now? Does the application write to files by any chance? You can navigate there inside the bash and take a look.

Better yet, once you found out what’s going wrong you can try it there and then, so you’re sure that your image command is not wrong and will work once you get the details right.

Build Better Images

Do you want to learn more about building Docker images and running containers without having them crash four out of five tries?