Where’s that log file? Debugging failed Docker builds

You’ve got a nice new Dockerfile, and it’s time to try it out:

$ docker build -t mynewimage .
Sending build context to Docker daemon  3.072kB
Step 1/3 : FROM python:3.8-slim-buster
 ---> 3d8f801fc3db
Step 2/3 : COPY build.sh .
 ---> 541b65a7b417
Step 3/3 : RUN ./build.sh
 ---> Running in 9917e3865f96
Building some more...
Build failed, see /tmp/builderr024321.log for details
The command '/bin/sh -c ./build.sh' returned a non-zero code: 1

So—now what? That log file isn’t on your host computer’s filesystem, it’s in the temporary image that build was creating.

How do you read that log file? By understanding just a little bit more about how Docker builds image.

How Docker builds images

To a first approximation, Docker builds images inside containers. In particular, each RUN command is a new container started from the image created by the previous step, running whatever the command is.

That means that build.sh step was run in a container.

We can list containers:

$ docker container ls

Nothing there—because it’s not a running container. So let’s look at dead containers:

$ docker container ls -a
CONTAINER ID   IMAGE          COMMAND                  CREATED         STATUS
9917e3865f96   541b65a7b417   "/bin/sh -c ./build.…"   3 minutes ago   Exited (1) 3 minutes ago

And there it is!

If you have multiple dead containers, you can recognize yours either by the command line, or by the image ID. Notice that the image ID, 541b65a7b417, is the same as the image ID created in step 2 in the docker build we ran earlier.

It’s in the container!

We’ve made some progress: we know that the log file is probably inside that container. And now we can copy the file out of the container.

The container ID is 9917e3865f96, but we can just use the first few characters to refer to it:

$ docker container cp 9917:/tmp/builderr024321.log .
$ cat builderr024321.log
Error, missing flux capacitor!

And there you have it: the build failed because of a missing flux capacitor.

Learn how to build fast, production-ready Docker images—read the rest of the Docker packaging guide for Python.