What does docker:connect_no_route_to_host mean?

Docker cannot reach the registry host because the network path has no usable route, the gateway is blocked, or the destination subnet is unreachable.

How do I prevent docker:connect_no_route_to_host in CI?

Keep runner routing, VPN, and firewall policy consistent across environments. Add a simple registry reachability check in CI before pull or push steps.

connect: no route to host

Q: How can I manually validate docker:connect_no_route_to_host?

Resolve the registry host first: `nslookup ` or `getent hosts `. Check routing to the resolved IP with the host routing tool, for example `ip route get ` on Linux. Once routing looks correct, test the endpoint directly: `nc -vz 443` or `curl -vkI https:// /v2/`.

Fix it fast

Most likely: The machine or CI runner has no usable network route to the registry IP, often because of VPN, firewall, security-group, gateway, or split-DNS routing.

1. Confirm this is your error

connect: no route to host

2. Check the cause

nslookup <registry>
ip route get <registry-ip>
nc -vz <registry> 443
curl -vkI https://<registry>/v2/

3. Apply the safe fix

# Fix the network route first: VPN, gateway, firewall, security group, runner egress, or split-DNS policy.

# After direct connectivity works, retry Docker with debug output.
docker --debug pull <image>

4. Verify it works

nc -vz <registry> 443
curl -vkI https://<registry>/v2/
docker pull <image>

Don't use unsafe shortcuts

Do not change Docker login, image tags, or TLS settings until basic routing to the registry works.
Do not validate only from your laptop if the failing environment is a CI runner, VM, or remote Docker host.
Do not treat no route to host as a registry application error, the request is failing before Docker reaches the registry service.

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

Resolve the registry host and confirm it returns the expected IP for this environment, fix the route, gateway, VPN, firewall, or runner egress policy so the host can actually reach that IP, and only after basic routing works, retry with docker --debug pull <image> to confirm Docker now reaches the endpoint.

Proof the route really fails

Resolve the registry host first with nslookup <registry> or getent hosts <registry>, check routing to the resolved IP with the host routing tool, for example ip route get <registry-ip> on Linux, and once routing looks correct, test the endpoint directly with nc -vz <registry> 443 or curl -vkI https://<registry>/v2/.

Why It Happens

Usually this comes down to the host has no valid route to the registry subnet, or the default gateway is down, a firewall, security group, VPN, or network policy blocks egress before the registry can be reached, or the registry hostname resolves to an address that is unreachable from this machine or runner.

Prove the Failing Environment Can Reach It

A direct check such as nc -vz <registry> 443 succeeds from the same machine or runner, and re-run the original pull or push and confirm no route to host is gone.

How route failures stop registry access

This is the part worth understanding if the quick fix did not hold. It explains what Docker is trying to do at the moment the error appears.

Before Docker can speak TLS or HTTP, the host must resolve the registry and find a usable route to its IP address.

If the kernel cannot route packets to that destination, the request fails with no route to host before any registry response is returned.

Prevent Repeat Connectivity Failures

To prevent this, keep runner routing, VPN, and firewall policy consistent across environments, and add a simple registry reachability check in CI before pull or push steps.