Docker build log cleaner for coding agents

Before and after

$ docker buildx build --progress=plain -t api-image .
#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 1.28kB done
#1 DONE 0.0s
#2 [internal] load metadata for docker.io/library/python:3.12-slim
#2 DONE 0.8s
#3 [1/5] FROM docker.io/library/python:3.12-slim
#3 CACHED
#4 [2/5] WORKDIR /app
#4 CACHED
#5 [3/5] COPY requirements.txt ./
#5 DONE 0.1s
#6 [4/5] RUN pip install --no-cache-dir -r requirements.txt
#6 1.322 Collecting fastapi==0.111.0
#6 1.944 Collecting psycopg2==2.9.9
#6 2.101 ERROR: Could not find a version that satisfies the requirement private-package==0.4.0 (from versions: none)
#6 2.102 ERROR: No matching distribution found for private-package==0.4.0
#6 ERROR: process "/bin/sh -c pip install --no-cache-dir -r requirements.txt" did not complete successfully: exit code: 1

Dockerfile:9
--------------------
   7 | COPY requirements.txt ./
   8 |
   9 | >>> RUN pip install --no-cache-dir -r requirements.txt
  10 | COPY . .
--------------------
ERROR: failed to solve: process "/bin/sh -c pip install --no-cache-dir -r requirements.txt" did not complete successfully: exit code: 1

Debug Docker build failure.

Type:
- Docker build

Keep:
- cmd: docker buildx build --progress=plain -t api-image .
- base image: python:3.12-slim
- failing step: #6 [4/5] RUN pip install --no-cache-dir -r requirements.txt
- Dockerfile:9 -> RUN pip install --no-cache-dir -r requirements.txt
- error: No matching distribution found for private-package==0.4.0
- exit: process did not complete successfully: exit code: 1

Folded:
- cached layers, dockerfile transfer, package download chatter, repeated solve wrapper lines

Ask: root cause, smallest fix, verify command.

Read the failing build boundary first

Start with the last BuildKit step marked as failed and connect it to the Dockerfile line. The step tells you which stage and command were executing; the Dockerfile context tells you what the image intended to do. Earlier CACHED and DONE steps establish that the build reached this boundary, but repeating all of them rarely helps diagnose the failure.

Inside the failing step, keep the most specific tool error. A package resolver saying “No matching distribution” provides more evidence than Docker’s later “process did not complete successfully.” Authentication failures, DNS errors, unavailable package versions, compiler errors, and disk-space failures all exit with a non-zero code, but they require different verification steps.

Multi-stage builds add another decision. Preserve the stage name, base image, and copied artifact path when the failing command depends on files produced earlier. A build-time failure is also different from a container startup failure: runtime logs usually need the command, exit status, health-check result, and application error rather than Dockerfile step output.

Build a narrow reproduction

• Use plain progress output so the failing step, command, and package-manager message remain visible.
• Re-run the package or compiler command in the same base image when that can isolate the failure without changing the Dockerfile.
• Preserve the lockfile, package index, architecture, and runtime version when dependency resolution is involved.
• Separate network or credential verification from package-version changes so one test answers one question.
• Use a no-cache rebuild only when cache behavior is part of the hypothesis; it is not a universal fix.

What TokenSift does with Docker output

The Docker parser retains the build command, failing step, Dockerfile location, failed command, base-image hints, package-manager evidence, and exit details. It folds successful cache/export lines, download progress, and repeated npm warnings into named categories. It also keeps peer-dependency evidence when npm reports an unresolved dependency tree.

TokenSift does not inspect the image, registry, build context, lockfile, credentials, or network. It cannot tell whether a package is private, whether a registry policy changed, or whether a secret mount was configured correctly unless that evidence appears in the pasted output. The brief is a compact record for investigation, not a successful-build prediction.

Limits and review checklist

• Confirm that the retained step is the first meaningful failure, not only the final Docker solve wrapper.
• Keep stage names and architecture details for multi-platform or multi-stage builds.
• Restore a warning when the failing tool explicitly refers back to it.
• Remove registry credentials, internal image names, private URLs, and customer data before submission.
• Ask for the smallest Dockerfile or command change plus a command that verifies only that hypothesis.

See How TokenSift works, the Docker support matrix, and the guide to evidence-preserving debugging briefs.

Privacy note: No LLM API call. No raw logs sent to external model providers, ad providers, or third-party analytics. Hosted submissions may be stored in a private first-party database for diagnostics and retained for up to 30 days by default, so review and redact before use.

Open tokensift and paste your own log.