What does docker:timeout_exceeded mean?

Docker timed out while waiting for the registry response, which usually points to slow network links, proxy issues, or an overloaded registry.

How do I prevent docker:timeout_exceeded in CI?

Use a proxy/cache registry to reduce dependence on upstream availability. Keep runner network configuration consistent (DNS/proxy/firewall).

How can I manually validate docker:timeout_exceeded?

Resolve the target host from the same machine, container, or CI runner that failed. Use `nslookup ` or `dig ` so you know DNS is pointing where you expect. Test the target port directly with `nc -vz ` or `curl -Iv https:// /` to separate routing and proxy issues from package-manager behavior. If the failure only happens in CI, run the same checks in that runner image or job environment instead of validating from your laptop.

request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

Fix it fast

Most likely: Docker connected far enough to wait for a response, but the registry, proxy, VPN, firewall, or slow network path did not return headers before the client timeout.

1. Confirm this is your error

request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

2. Check the cause

docker --debug pull <image>
nslookup <registry>
curl -vkI --max-time 20 https://<registry>/v2/
docker info

3. Apply the safe fix

# Fix the slow or blocked path used by the Docker daemon: proxy, VPN, firewall, registry health, or runner network.

# If a proxy is required, configure it for Docker Desktop or the Docker daemon, then retry.
docker --debug pull <image>

4. Verify it works

curl -vkI --max-time 20 https://<registry>/v2/
docker pull <image>
docker push <image>

Don't use unsafe shortcuts

Do not keep rerunning the same CI job without changing network, proxy, or registry conditions.
Do not check only your shell proxy variables, Docker may use daemon-level proxy settings.
Do not debug image tags first if the failure is waiting for registry response headers.

Where the Request Failed

Docker is telling you the request failed before it got a clean response back. Treat the connection path and the failing environment as the first suspects, not the package or image name.

Restore connectivity to the registry or daemon endpoint

Retry with debug logs:docker --debug pull <image>

Validate DNS and connectivity to the registry host from the same machine.

If you use a proxy, ensure Docker is configured to use it (daemon + CLI env).

If the registry is internal, confirm health and TLS cert validity.

Manual network checks

Resolve the target host from the same machine, container, or CI runner that failed. Use nslookup <host> or dig <host> so you know DNS is pointing where you expect.

Test the target port directly with nc -vz <host> <port> or curl -Iv https://<host>/ to separate routing and proxy issues from package-manager behavior.

If the failure only happens in CI, run the same checks in that runner image or job environment instead of validating from your laptop.

Why It Happens

Usually this comes down to DNS, firewall, proxy, or VPN is blocking registry traffic, the registry is temporarily unavailable or overloaded, or corporate proxies are interfering with TLS or long-lived connections.

Prove the Failing Environment Can Reach It

Re-run the original pull/push and confirm it completes, and confirm CI runners can reach the same registry endpoint.

How Docker pulls and pushes images

Docker has to resolve the host, open a route, and complete the network connection before it can read image metadata or transfer content from the registry or daemon endpoint. That is why these failures are usually solved at the environment layer first. Until the same machine or CI runner can reach the target cleanly, changing versions or names rarely helps.

Prevent Repeat Connectivity Failures

To prevent this, use a proxy/cache registry to reduce dependence on upstream availability, and keep runner network configuration consistent (DNS/proxy/firewall).