While building a Docker image for a Go app, I encountered problems and struggled to identify the root cause due to unhelpful error messages. In such situations, it's helpful to inspect the intermediate layers of your Docker image to pinpoint the root cause of the issue.

Understanding Docker Image Layers

In Docker, each instruction in a Dockerfile creates a new layer. These layers are stacked on top of each other to form the final image. This layering system is useful because it allows you to inspect what's happening at each step of the Dockerfile.

Accessing Individual Layers

By default, Docker uses Buildkit to build images, which doesn't expose the IDs of intermediate images during the build process. To access individual layers, you need to create your image using the traditional build process. You can enable this by running the following command:

This command will print the IDs of the intermediate images for each step, similar to the following output:

With the image layer IDs, you can run a container from a specific layer and start an interactive shell (/bin/sh) inside it. This allows you to inspect files, run commands, and test configurations directly within that layer:

How did this help me?

In my case, I noticed that a particular file had incorrect permissions set, which was causing issues during the Docker build process. By starting a container from an intermediate layer image and using /bin/sh to navigate the filesystem, I identified the file with incorrect permissions.