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.

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:
#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: 100Reproduce the four common classes locally:
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/pipfailed 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 fragment | Real cause | Fix |
|---|---|---|
did not complete successfully: exit code: 100 | apt could not fetch or resolve a package | Fix the repo list or pin the distro; combine update and install in one RUN |
exit code: 127 | Command not in PATH inside that image | Use sh -c 'command -v x' to check, or install it |
failed to compute cache key: "/x" not found | File not in the build context | Check .dockerignore, the build context path, and . |
failed to read dockerfile | Wrong -f path or missing file | Pass an explicit -f and build from the repo root |
Temporary failure resolving | Build sandbox has no DNS | --network=host, a --dns flag, or an internal mirror |
connect: connection refused / i/o timeout | Egress blocked or proxy required | Proxy build args and ENV in the stage |
failed to authorize: 403 | Registry credentials missing for FROM | docker login, or --secret for a private base |
no space left on device | Build cache or image layers filled the disk | docker buildx prune -f, check /var/lib/docker |
| Approach | Works when | Cost |
|---|---|---|
--network=host | Daemon on Linux, trusted build | Build has full host network |
Proxy ARG/ENV in the stage | Corporate egress | Proxy URL baked into layers if used with ENV |
--mount=type=cache | Repeated package downloads | Stale cache hides a changed index |
BuildKit --secret | Private tokens at build time | Not stored in the layer |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. apt failures: pin the distro and combine the steps
# 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
docker build -f docker/Dockerfile . # context is the repo root
docker build -f Dockerfile docker/ # context is docker/ — COPY ../src failsCOPY ../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:
docker build --build-context shared=../shared -f docker/Dockerfile .COPY /src /app/src3. Network access during a build
# 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.tgzdocker 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:
ARG HTTPS_PROXY
RUN if [ -n "$HTTPS_PROXY" ]; then \
export https_proxy="$HTTPS_PROXY" http_proxy="$HTTPS_PROXY"; fi; \
npm ci --omit=dev4. Cache mounts that hide a change
RUN \
pip install -r requirements.txtThe 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:
RUN \
pip install -r requirements.txtTo 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
# syntax=docker/dockerfile:1.7
RUN \
npm ci --omit=devdocker 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
docker buildx du # what the builder holds
docker buildx prune --filter until=168h -f
docker system df -v | headno 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
| Mistake | Symptom | Correct approach |
|---|---|---|
apt-get update in its own layer | 404 on a package version | Combine with install |
Copying a file excluded by .dockerignore | failed to compute cache key | Fix .dockerignore |
Expecting COPY ../x to work | not found | Root context or named context |
| Relying on host network implicitly | DNS or connection failures | --network=host explicitly |
ENV for proxy or token | Secret in the image history | ARG for proxy, --secret for tokens |
--no-cache as a first response | Slow and usually irrelevant | Read the exit code first |
| Building on macOS and assuming Linux semantics | Case-insensitive paths, no --network=host | Build 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 toolsSmall utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Docker guides
All Docker guidesDocker Inspect: Go Templates, Format Flags, and JSON Filtering
The fields worth knowing, the array-versus-object trap, and why <no value> silently passes your monitoring check instead of failing it.
Docker Restart Policies: no, on-failure, always, and unless-stopped
What each policy really restarts, why on-failure ignores a clean exit, how backoff hides crash loops, and why health checks never trigger a restart.
Docker Compose Profiles: Multi-Environment Configs and Overrides
Profiles select which services exist; override files change how they run. How the two fit together, and why ports concatenate instead of replacing.
Docker COPY vs ADD: Build Context, .dockerignore, and Cache Busting
ADD adds tar extraction and URLs nobody wants; COPY is the predictable choice. How the build context is packed, and how copy order decides rebuild time.
More in Docker
All Docker guidesThe guides filed next to this one in Docker, in library order.