How Can I Inspect the File System of a Failed Docker Build?

TLDR

To inspect the file system of a failed Docker build, use multi-stage builds to save intermediate images, add debug steps (like sleep or tail), or leverage BuildKit's --target and --output features. This lets you start a shell in the failed state and debug interactively.

Why Is This Useful?

When a Docker build fails, you often want to see what files, environment variables, or installed packages are present at the failure point. This helps you debug missing files, permissions, or unexpected build behavior.

Method 1: Add a Debug Step (sleep or tail)

Temporarily add a line to your Dockerfile before the failing step:

RUN sleep infinity

or

RUN tail -f /dev/null

Build the image:

docker build -t debug-image .

In another terminal, find the running container:

docker ps

Start a shell in the container:

docker exec -it <container_id> /bin/bash

Now you can inspect the file system, check logs, and debug interactively. When done, remove the debug line from your Dockerfile.

Method 2: Use Multi-Stage Builds to Save Intermediate State

If your build uses multi-stage builds, you can tag an intermediate stage and run a container from it:

FROM ubuntu:22.04 as builder
# ... build steps ...

FROM builder as debug-stage
# Add a debug step if needed

Build up to the debug stage:

docker build --target debug-stage -t debug-image .
docker run -it debug-image /bin/bash

Method 3: Use BuildKit's --output=type=local

With BuildKit enabled, you can export the build's file system to a local directory:

docker build --output type=local,dest=./output .

This writes the final build context to ./output, so you can inspect files directly on your host.

Method 4: Commit a Stopped Container (if build got far enough)

If your build ran a container that exited, you can commit it to an image:

docker ps -a  # Find the exited container
# Then:
docker commit <container_id> debug-image
docker run -it debug-image /bin/bash

Best Practices

• Remove debug steps after you're done to keep images clean.
• Use multi-stage builds to avoid leaking secrets or build tools into final images.
• For complex builds, consider using BuildKit for advanced debugging features.

Conclusion

Inspecting the file system of a failed Docker build is easy with debug steps, multi-stage builds, or BuildKit's output features. Use these techniques to troubleshoot and fix build issues faster.