Docker buildx has an integtrated debugger #docker

How did I miss this? Late in 2023, Docker buildx v0.12.0 introduced an integrated debugger for image building. This is a great feature to help you analyze why a build is failing. Instead of reading the build output you can now check the build interactively after it failed.

Mind this is still an experimental feature which is unlocked by executing export BUILDX_EXPERIMENTAL=1.

This feature of buildx also requires at least BuildKit v0.N.0.

buildx has recently added the debug subcommand enabling interactive debugging of failed container image builds. This feature is especially useful for debugging complex multi-stage builds. The debug subcommand allows you to inspect the build environment, run commands, and modify the build context to help diagnose build failures.

The following command will drop you into /bin/sh in the build container:

export BUILDX_EXPERIMENTAL=1
docker buildx debug build .

You can customize the command, e.g. to set your favorite shell which must be available in the container image at the stage of the failure:

export BUILDX_EXPERIMENTAL=1
docker buildx debug --invoke=/bin/bash build .

This greatly improves developing a new Dockerfile which usually be some an endless loop of editing and building - wasting a lot of time. With the interactive debug, the fix is created in the context of the build and is implemented in the Dockerfile after testing.

This also features a monitor mode which allows you to control the debug environment. You can switch between the shell and the monitor mode by pressing Ctrl-a-c.

Also refer to the official documentation.

Related tools

Interactive debugger buildg for image builds with integration into IDEs

Tools for debugging running containers called cdebug

Docker Desktop comes bundled with docker debug for troubleshooting running containers

Are you running outdated versions?

Checkout uniget to install and update your favorite tools!