🚨 Docker Error Guide: 'context canceled' Build and Pull Cancellation Failures

Exact Error Message

context canceled shows up when a Docker operation — usually a build or pull — is aborted before it finishes:

docker build -t app:latest .

------
 > [builder 4/9] RUN go mod download:
------
ERROR: failed to solve: failed to fetch ...: context canceled

docker pull registry.example.com/app:1.2.3

failed to copy: httpReadSeeker: failed open: context canceled

ERROR: failed to receive status: rpc error: code = Canceled desc =
context canceled

The word “canceled” is the clue: something asked the operation to stop. The build/pull didn’t fail on its own merits — its surrounding context was cancelled out from under it.

What the Error Means

Go programs (the Docker CLI, daemon, BuildKit, and containerd are all Go) carry a context.Context through long-running operations. When that context is cancelled — because of a timeout, a signal, a closed connection, or a parent operation aborting — every in-flight call returns context canceled. So this error is not a root cause; it’s the symptom of whatever cancelled the context.

The real trigger is usually one of: the client was interrupted (Ctrl-C, CI step timeout, SSH session dropped), the daemon or BuildKit was restarted mid-operation, a network/registry connection stalled past a deadline, or a multi-stage build had one stage fail and BuildKit cancelled the sibling stages. The fix is to find who cancelled the context, not to retry blindly — though a clean retry often succeeds if the cancellation was transient.

Common Causes

• Client interrupted. Ctrl-C, a CI job/step timeout, or a dropped SSH/terminal session kills the CLI, cancelling the build’s context.
• Daemon or BuildKit restarted mid-build (a systemctl restart docker, an OOM kill of the daemon, or a host reboot).
• Network stall to the registry. A pull/RUN-fetch hangs and a deadline elapses, cancelling the transfer.
• A failing parallel stage. In a multi-stage or multi-platform build, one stage erroring causes BuildKit to cancel the others, which then report context canceled.
• docker build over a remote/SSH context where the connection drops.
• Resource pressure (OOM, disk full) causing the daemon to kill or restart a worker.

How to Reproduce the Error

Start a build that does meaningful work, then interrupt it — the cancelled context surfaces as the error:

printf 'FROM alpine:3.20\nRUN sleep 30\n' > Dockerfile
docker build -t cancel-demo . &
BUILD_PID=$!
sleep 3 && kill -INT $BUILD_PID
wait $BUILD_PID

ERROR: failed to solve: ... context canceled

Any externally-imposed stop (a CI step timeout, a closed shell) produces the same result.

Diagnostic Commands

First determine whether the daemon or BuildKit restarted during the failing window:

systemctl status docker --no-pager | grep -i 'active\|since'
journalctl -u docker --since "20 min ago" | grep -i 'restart\|signal\|killed\|oom'

Check for resource pressure that could have killed a worker:

df -h /var/lib/docker
df -i /var/lib/docker
dmesg | grep -i 'killed process\|out of memory' | tail

Look at the build history / active builds and the CLI exit context:

docker builder du
journalctl -u docker --since "20 min ago" | grep -i 'context canceled\|deadline\|canceled'

In CI, check whether the job hit its own time limit (the surrounding system, not Docker, cancelled it).

Step-by-Step Resolution

Cause: client interruption / CI timeout. Confirm the CI step’s timeout is longer than the build needs, ensure nobody is sending Ctrl-C, and keep the connection alive. For long builds over SSH, run them detached or raise the step timeout, then re-run:

docker build -t app:latest .

A clean re-run usually succeeds once the interruption source is removed.

Cause: daemon/BuildKit restart. If the log shows a restart during the build, find why it restarted (manual restart, host reboot, OOM of the daemon). Avoid restarting Docker during builds; if it was OOM-killed, free memory or raise limits, then rebuild.

Cause: network stall. Improve registry reliability — use a closer mirror, retry transient RUN fetches, and ensure DNS/proxy are healthy. The TLS handshake timeout guide covers stalled-registry-connection diagnosis.

Cause: failing parallel stage. The real failure is the other stage, not the cancelled one. Build stages individually to find the true error:

docker build --target builder -t app:builder .

Fix the stage that actually errors; the context canceled on its siblings then disappears.

Cause: resource pressure. Reclaim disk and inodes (docker builder prune) and ensure the host has headroom, then rebuild. See the no space left on device guide is referenced elsewhere; here, watch df and dmesg for OOM.

A worked example. A nightly image build began failing with failed to solve: ... context canceled at a random stage each run. The journal showed the Docker daemon being OOM-killed and restarted right before each failure: a parallel RUN npm ci stage spiked memory above the node’s limit, the kernel killed the daemon, and every in-flight build context was cancelled. Capping the build’s memory with BuildKit and giving the node more RAM stopped the OOM, the daemon stayed up, and builds completed. The cancellation was always a consequence of the OOM, never the cause.

Prevention and Best Practices

• Set CI build-step timeouts comfortably above the build’s real duration and avoid sending interrupts.
• Don’t restart the Docker daemon (or reboot hosts) while builds are running; drain first.
• Keep build hosts with enough RAM/disk headroom so the daemon isn’t OOM-killed mid-build.
• Build and test stages individually when debugging multi-stage failures so the true error isn’t masked by sibling cancellation.
• Use reliable registries/mirrors and retry transient network fetches inside RUN steps.

Related Errors

• Docker Error Guide: ‘failed to solve with frontend dockerfile.v0’ — other BuildKit solve failures that aren’t cancellations.
• Docker Error Guide: ‘TLS handshake timeout’ — stalled registry connections that can lead to a cancelled context.
• See more Docker troubleshooting guides.

Frequently Asked Questions

Does retrying fix it? Often, if the cancellation was transient (a brief network stall or a one-off interruption). If it recurs, find the cancel source — a timeout, restart, or failing sibling stage.

Is context canceled ever the root cause? No. It always means an outer context was cancelled. The journal and CI logs tell you what cancelled it.

Why does it fail at a different step each time? Whatever step happens to be in flight when the context is cancelled reports the error. The pattern (random step) is itself a hint that an external event — restart, OOM, timeout — is the cause.

Could it be my Dockerfile? Only indirectly. A stage that errors can cancel its siblings. Build stages one at a time to find the real failure; the cancellation itself isn’t a Dockerfile bug.