How to Debug a Docker Build With progress plain in GitHub Actions

BuildKit collapses output by default; --progress=plain prints every layer command and its full stdout so you can read the failing step.

Add --progress=plain (and --no-cache when a cached layer hides the bug) to the build. With docker/build-push-action, set DOCKER_BUILDKIT and pass build args the same way.

Steps

• Add --progress=plain so each RUN prints its full output.
• Add --no-cache to rule out a stale cached layer.
• Read the expanded output for the real error in the failing layer.

Workflow

steps:
  - uses: actions/checkout@v4
  - name: Build with full output
    run: |
      docker build --progress=plain --no-cache \
        -t myapp:ci .
  # with the build-push action, plain progress is on by default in CI,
  # add no-cache when debugging a layer:
  - uses: docker/build-push-action@v6
    with:
      context: .
      no-cache: true

Gotchas

• Without --no-cache, a previously cached failing layer may not re-run and you never see the error.
• --progress=plain works only with BuildKit, which is the default in current Docker.
• For the deepest build trace, also set BUILDKIT_PROGRESS=plain in the environment.

Related guides