Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Docker BuildKit failed to solve: Exit Codes, Build Context, and Network

BuildKit puts every failure under one prefix. The exit code after did not complete successfully is the whole diagnosis: 100 is apt, 127 is a missing binary, and cache key is a file outside the context.

~5 min readDocker
#Docker#BuildKit#CI#Debugging
3D illustration of a build pipeline with a failing layer brick and a cache vault beside it

Introduction & Quick Summary

Symptom. docker build ends with ERROR: failed to solve: process "/bin/sh -c apt-get update && apt-get install -y curl" did not complete successfully: exit code: 100, or failed to compute cache key: "/package.json" not found, or failed to solve: failed to read dockerfile: open Dockerfile: no such file or directory, or a network trace such as Temporary failure resolving 'deb.debian.org' / dial tcp 151.101.2.132:443: connect: connection refused. BuildKit reports everything under one failed to solve prefix, which is why the actual cause is easy to miss.

Cause. BuildKit builds in a fresh container per instruction, so the failure is almost never Docker itself. It is the command's exit status (100 for apt, 1 for a shell, 127 for a missing binary), a file that is not in the build context (because of .dockerignore or because the heredoc/Dockerfile path is wrong), the sandbox having no network or no DNS, a proxy the daemon does not inherit, or a cache mount hiding an invalidated layer.

Fix. Read the second half of the message after did not complete successfully: — it carries the exit code and usually the failing command's own output above it. Then address the class: install step → add --no-install-recommends, apt-get update in the same layer, and check the base image's distro; missing file → check the context; network → --network=host for a build-time download or configure a proxy; cache → prune and rebuild without cache to confirm.

Core Mechanics, Signatures & Reproducible Setup

BuildKit builds a DAG of instructions, caches each result by content hash, and runs RUN steps in a sandboxed container with no host network by default. docker build in Buildx mode prints progress as #N [stage k/n] RUN … and, on failure, a summary block:

code
#12 [build 4/6] RUN apt-get update && apt-get install -y curl #12 0.412 Err:1 http://deb.debian.org/debian bookworm InRelease #12 0.412 Temporary failure resolving 'deb.debian.org' #12 ERROR: process "/bin/sh -c apt-get update && apt-get install -y curl" did not complete successfully: exit code: 100

Reproduce the four common classes locally:

bash
mkdir -p /tmp/bk && cd /tmp/bk cat > Dockerfile <<'EOF' FROM python:3.12-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD ["python", "app.py"] EOF echo "requests==2.32.3" > requirements.txt echo 'print("ok")' > app.py printf 'requirements.txt\n' > .dockerignore # now the COPY fails docker build -t bk-demo . # failed to compute cache key rm .dockerignore docker build --network=none -t bk-demo . # network failure for FROM/pip

failed to compute cache key is BuildKit's message for "the path you asked to copy is not in the context snapshot". It is not a caching bug and --no-cache will not fix it.

Key Comparison Table

Error fragmentReal causeFix
did not complete successfully: exit code: 100apt could not fetch or resolve a packageFix the repo list or pin the distro; combine update and install in one RUN
exit code: 127Command not in PATH inside that imageUse sh -c 'command -v x' to check, or install it
failed to compute cache key: "/x" not foundFile not in the build contextCheck .dockerignore, the build context path, and .
failed to read dockerfileWrong -f path or missing filePass an explicit -f and build from the repo root
Temporary failure resolvingBuild sandbox has no DNS--network=host, a --dns flag, or an internal mirror
connect: connection refused / i/o timeoutEgress blocked or proxy requiredProxy build args and ENV in the stage
failed to authorize: 403Registry credentials missing for FROMdocker login, or --secret for a private base
no space left on deviceBuild cache or image layers filled the diskdocker buildx prune -f, check /var/lib/docker
ApproachWorks whenCost
--network=hostDaemon on Linux, trusted buildBuild has full host network
Proxy ARG/ENV in the stageCorporate egressProxy URL baked into layers if used with ENV
--mount=type=cacheRepeated package downloadsStale cache hides a changed index
BuildKit --secretPrivate tokens at build timeNot stored in the layer

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. apt failures: pin the distro and combine the steps

dockerfile
# Broken: separate layers, stale index, interactive prompts RUN apt-get update RUN apt-get install -y curl git build-essential # Fixed RUN apt-get update \ && apt-get install -y --no-install-recommends curl git build-essential \ && rm -rf /var/lib/apt/lists/*

A cached apt-get update layer from last week combined with today's package list produces 404 Not Found for a version that no longer exists — exit code 100. Combining the two instructions forces a fresh index whenever the install changes. DEBIAN_FRONTEND=noninteractive prevents a tzdata prompt from hanging the build until a timeout, which BuildKit reports as a failed step with no output at all.

2. Files that are not in the context

bash
docker build -f docker/Dockerfile . # context is the repo root docker build -f Dockerfile docker/ # context is docker/ — COPY ../src fails

COPY ../shared/src /app/src never works, regardless of the Dockerfile's location: a build cannot read outside its context. Restructure to one context at the repository root, or use a named context:

bash
docker build --build-context shared=../shared -f docker/Dockerfile .
dockerfile
COPY --from=shared /src /app/src

3. Network access during a build

dockerfile
# A single download at build time, with a retry and a checksum RUN curl -fsSL --retry 3 -o /tmp/tool.tgz https://example.com/tool-1.2.3.tgz \ && echo "9f2c… /tmp/tool.tgz" | sha256sum -c - \ && tar -xzf /tmp/tool.tgz -C /usr/local/bin \ && rm /tmp/tool.tgz
bash
docker build --network=host -t app . # Linux daemon only docker build --build-arg HTTPS_PROXY=$HTTPS_PROXY -t app .

Behind a proxy, ARG is the portable form because ENV bakes the value into the image:

dockerfile
ARG HTTPS_PROXY RUN if [ -n "$HTTPS_PROXY" ]; then \ export https_proxy="$HTTPS_PROXY" http_proxy="$HTTPS_PROXY"; fi; \ npm ci --omit=dev

4. Cache mounts that hide a change

dockerfile
RUN --mount=type=cache,target=/root/.cache/pip \ pip install -r requirements.txt

The mount persists between builds, which is the point. The trap is a cache that contains a resolution made against a different index or Python version: pip reports Requirement already satisfied for a package that the new base image does not have, and the container fails at runtime. Add the index or a version stamp to the mount id:

dockerfile
RUN --mount=type=cache,id=pip-3.12,target=/root/.cache/pip \ pip install -r requirements.txt

To confirm the cache is the difference, run once with docker build --no-cache; if the failure disappears, it was the cache, not the Dockerfile.

5. Secrets without baking them into layers

dockerfile
# syntax=docker/dockerfile:1.7 RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \ npm ci --omit=dev
bash
docker build --secret id=npmrc,src=$HOME/.npmrc -t app .

The secret is mounted only for that instruction and does not appear in the layer or in docker history. ARG with a token does appear — in the layer's metadata — which is why ${TOKEN} in a RUN is a leak even after unset.

6. Disk pressure and pruning

bash
docker buildx du # what the builder holds docker buildx prune --filter until=168h -f docker system df -v | head

no space left on device during a multi-stage build usually means the builder cache, not the final image. --filter until=168h keeps a week of cache, which preserves most rebuild speed while reclaiming the bulk.

Common Compilation/Runtime Mistakes & Version Gotchas

MistakeSymptomCorrect approach
apt-get update in its own layer404 on a package versionCombine with install
Copying a file excluded by .dockerignorefailed to compute cache keyFix .dockerignore
Expecting COPY ../x to worknot foundRoot context or named context
Relying on host network implicitlyDNS or connection failures--network=host explicitly
ENV for proxy or tokenSecret in the image historyARG for proxy, --secret for tokens
--no-cache as a first responseSlow and usually irrelevantRead the exit code first
Building on macOS and assuming Linux semanticsCase-insensitive paths, no --network=hostBuild in CI or use --platform=linux/amd64

Version notes: BuildKit is the default builder since Docker 23, so DOCKER_BUILDKIT=0 no longer works on current engines and old --cache-from workflows behave differently under Buildx. # syntax=docker/dockerfile:1.7 at the top of the Dockerfile is required for --mount=type=secret and --mount=type=cache on older engines; without it the RUN --mount line is parsed as a shell command and fails with unknown flag: --mount. Docker 28 moved more engine defaults onto containerd, so a runner pinned to a different engine version can fail at the networking step while the same Dockerfile builds on a laptop — pin the engine version in CI rather than debugging per-run flakiness.

For the diagnostics around a build, the text diff tool compares two Dockerfiles when a "working" file diverges from the one in CI, the base64 tool decodes an auth entry from docker config when a base image pull needs credentials, and the hash tool computes the checksum you want to pin next to a downloaded artifact. Build output that ends in a JSON error from a registry (failed to authorize: ... {"errors":[…]}) is easiest to read after a pass through the JSON formatter.

Try matching browser tools

All tools

Small utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Docker guides

More in Docker

All Docker guides

The guides filed next to this one in Docker, in library order.