How to debug Docker build failures

How to debug Docker build failures

When a docker build is failing for me I find that a great way to understand what's causing the failure is to jump into the container in an interactive terminal and have a poke around. This used to be easy because Docker would build an image and cache it for each step in your dockerfile and output the id for that image. Since  BuildKit became the default build tool those images are no longer made available and you just see an output like this.

Now you could disable BuildKit in your docker config but that would make all your builds worse™ so instead what I do is temporarily disable BuildKit by setting the DOCKER_BUILDKIT environment variable to 0. You can easily do this on the same line as your build command whatever shell you're using.


Powershell
$env:DOCKER_BUILDKIT=0; docker build .
Linux/macOS
DOCKER_BUILDKIT=0 docker build .
Windows CMD
set DOCKER_BUILDKIT=0& docker build .

This give will tell docker to use the legacy build tooling and so I'll get the id of each  image for each step.

So for the example above I can see that the last successful step is 1/2 and it produced an image 14119a10abf4. I can run that image and connect to an interactive shell using the following command and debug away.

docker run -it 14119a10abf4 sh