🚨 Docker Error Guide: 'context deadline exceeded' — Fix Registry & Daemon Timeouts

Overview

context deadline exceeded is Go’s way of saying an operation ran past the timeout Docker gave it and was cancelled. Because the Docker CLI, daemon, and BuildKit are all written in Go, this message surfaces almost anywhere a network call or long-running task blocks — a pull, a push, a build, an API call, or a health probe. The literal error usually looks like this during a pull:

Error response from daemon: Get "https://registry-1.docker.io/v2/": context deadline exceeded (Client.Timeout exceeded while awaiting headers)

It is a timeout, not a hard failure: the remote endpoint was reachable enough to start the request but did not answer within the deadline. That distinction drives the whole diagnosis — you are looking for something slow, not something broken.

Symptoms

• docker pull or docker push aborts partway with context deadline exceeded.
• docker build stalls on [internal] load metadata or a FROM line, then fails with the same message from BuildKit.
• docker ps, docker info, or any CLI command hangs for ~30 seconds and then prints the error, pointing at the daemon socket rather than a registry.
• Intermittent failures on a CI runner that succeed on retry, especially behind a corporate proxy.
• Health checks flip to unhealthy with context deadline exceeded in the probe output.

Common Root Causes

• Slow or throttled registry — the registry is rate-limiting, degraded, or geographically distant, so headers arrive after the client timeout.
• Proxy / firewall latency — an HTTP proxy or deep-packet-inspection firewall adds seconds per request, or silently drops the connection after the TLS handshake.
• DNS resolution delay — a slow or misconfigured resolver makes every registry lookup take seconds before the request even starts.
• Overloaded daemon — the daemon is pegged (huge image, disk I/O saturation, thousands of containers) and cannot service the API call within the CLI’s deadline.
• MTU / VPN path issues — large TLS records fragment on a VPN with a smaller MTU, so the handshake stalls until the deadline.
• Registry mirror misconfigured — daemon.json points at a registry-mirror that is down or unreachable, so every pull waits for it to time out.

Diagnostic Workflow

Confirm whether the deadline is hit talking to a registry or to the daemon itself. Time a plain CLI call:

time docker info

If docker info is instant but pulls fail, the problem is registry/network. If docker info itself hangs, the daemon is overloaded or stuck — check it directly:

systemctl status docker
journalctl -u docker --since '15 min ago' | grep -i 'deadline\|timeout\|context'

Test raw connectivity and latency to the registry, bypassing Docker:

time curl -sS -o /dev/null -w '%{http_code} %{time_total}s\n' https://registry-1.docker.io/v2/
docker pull hello-world        # smallest possible image isolates network vs. size

Check DNS resolution speed, since a slow resolver is a frequent hidden cause:

time getent hosts registry-1.docker.io
docker run --rm busybox nslookup registry-1.docker.io

Inspect the daemon config for a bad mirror or proxy:

cat /etc/docker/daemon.json
systemctl show docker --property=Environment   # HTTP_PROXY / HTTPS_PROXY / NO_PROXY
docker info | grep -i -A2 'registry mirror\|proxy'

For a build, get BuildKit’s verbose progress so you can see exactly which step times out:

docker build --progress=plain -t myapp:test .

Example Root Cause Analysis

A CI runner behind a corporate proxy began failing every docker build on the FROM node:20 line with context deadline exceeded, while the same build passed on a laptop. time docker info returned instantly, ruling out an overloaded daemon. time curl https://registry-1.docker.io/v2/ from the runner took 31 seconds and then returned 401 (expected) — proving the registry was reachable but painfully slow through the proxy. systemctl show docker --property=Environment revealed HTTPS_PROXY was set for the daemon but NO_PROXY did not include the internal registry mirror, so pulls were being routed out through the slow corporate proxy and back. Adding the mirror host to NO_PROXY in the daemon’s systemd drop-in and restarting Docker dropped the request time to under a second and eliminated the timeouts. Root cause: proxy routing latency, not a Docker or registry fault.

Prevention Best Practices

• Set a pull-through registry-mirror close to your build hosts so metadata and layer requests are fast and cached.
• Get proxy config right at the daemon level (systemd drop-in), and always populate NO_PROXY with internal registries and 127.0.0.1.
• Monitor registry latency from your runners and alert before it approaches the client timeout, rather than discovering it in a failed deploy.
• Authenticate to Docker Hub (or use a mirror) to avoid anonymous rate limits that manifest as slow, timing-out responses.
• Keep the daemon healthy: cap image sizes, watch disk I/O, and prune regularly so it can service API calls promptly.
• On VPNs, verify path MTU; clamp MSS if large TLS handshakes stall.

Quick Command Reference

time docker info                         # daemon responsiveness vs. network
docker pull hello-world                  # smallest image; isolate network from size
time curl -sS -o /dev/null -w '%{http_code} %{time_total}s\n' https://registry-1.docker.io/v2/
time getent hosts registry-1.docker.io   # DNS latency
journalctl -u docker --since '15 min ago' | grep -i deadline
systemctl show docker --property=Environment   # proxy vars seen by the daemon
docker build --progress=plain -t myapp:test .  # see which build step times out
cat /etc/docker/daemon.json              # check registry-mirror / config

Conclusion

context deadline exceeded is a symptom of slowness, not breakage — Docker cancelled an operation that overran its deadline. The fastest path to a fix is to first split the problem in two: time docker info to tell a struggling daemon apart from a slow network, then time a raw curl to the registry to separate DNS, proxy, and registry latency. Once you know which hop is slow — a distant registry, a proxy without NO_PROXY, a sluggish resolver, or an overloaded daemon — the remedy (a mirror, corrected proxy config, faster DNS, or a healthier host) follows directly. Related timeout errors and more fixes live in the Docker guides.