Why Docker Hub Times Out in Clash
A browser that opens websites successfully is not proof that Docker can reach Docker Hub. Browsers usually follow the system proxy, a browser extension, or a locally configured HTTP proxy. Docker, however, is a separate service with its own daemon, DNS resolver, connection pool, and startup environment. It may ignore the proxy settings that your browser uses every day.
When Docker Hub access fails through Clash, the visible error is often a long pause followed by i/o timeout, context deadline exceeded, TLS handshake timeout, or net/http: request canceled. These messages can be caused by an unreachable proxy node, an incorrect Clash rule, DNS resolution outside Clash, blocked direct traffic, or a Docker daemon that has never been told to use the proxy.
This guide presents a practical troubleshooting path for Clash Verge, Clash Verge Rev, Mihomo, and other Clash-compatible clients. The goal is not to force every application through a proxy. Instead, we will test each layer separately, identify where the connection breaks, and configure Docker at the daemon level so that image pulls and registry authentication use a reliable route.
Technical Goal
Make Docker Hub image pulls reliable without confusing browser proxy settings, Clash routing rules, DNS behavior, and Docker daemon configuration.
1Identify the Failure Layer First
Do not begin by changing several YAML sections at once. A systematic diagnosis is faster because every test answers a specific question. First determine whether the selected Clash node can reach Docker Hub. Next verify that Clash is receiving the request. Finally check whether the Docker daemon is actually using that route.
Test the node outside Docker
Open the Clash client and select a node that is known to work for ordinary HTTPS traffic. In the client dashboard, make sure the proxy mode is not accidentally set to DIRECT. Then use the client’s connection or traffic log while opening Docker Hub in a browser. You should see requests involving domains such as registry-1.docker.io, auth.docker.io, and index.docker.io.
From a terminal, you can also test the registry endpoint through the local HTTP or SOCKS port exposed by Clash. Replace 7890 with the actual mixed or HTTP port shown by your client:
A healthy response is commonly 401 Unauthorized. That status is expected: Docker Hub requires authentication for many registry operations, but it proves that the server was reached and responded. A timeout, connection refusal, or name-resolution error points to Clash, the node, or DNS rather than Docker credentials.
Compare direct and proxied results
Run a direct test as a comparison:
If the direct request fails while the proxied request returns 401, Docker Hub traffic should be routed through Clash. If both requests fail, the selected node may be unavailable, the endpoint may be temporarily rate-limited, or your network may be blocking the connection before Clash can help. If both succeed but docker pull still times out, the daemon configuration is the most likely problem.
Important Diagnostic Signal
A Docker Hub 401 response is usually a successful connectivity test, not a failure. Focus on timeouts, refused connections, and TLS errors instead of treating every non-200 response as a network problem.
2Check Clash Rules for Docker Hub
In Rule mode, Clash evaluates traffic from top to bottom. A broad rule placed above a Docker-specific rule can send registry traffic directly, to a blocked group, or to a policy group whose selected node is offline. This is especially common when a subscription profile contains country-based rules, ad-blocking rules, or a final DIRECT fallback.
The most useful first step is to watch the Clash connection log while running a pull. On Windows, start a command such as:
At the same time, filter the Clash log for Docker-related hostnames. If no Docker Hub request appears, Docker is probably not using Clash at all. If the request appears with a DIRECT label, a rule or mode is bypassing the proxy. If it appears under the expected proxy group but still fails, test another node and inspect DNS or TLS behavior.
Use explicit registry rules
For a controlled configuration, place Docker Hub rules before broad regional or direct rules. The exact hostnames can change over time, so start with the core registry and authentication domains and expand only when the connection log shows another required endpoint:
Here, PROXY must match the name of an existing proxy group in your profile. Some subscriptions call the group Proxy, 🚀 Proxy, or 节点选择. YAML values are not automatically interchangeable: using a group name that does not exist can cause a configuration error or unexpected fallback behavior.
Do not add every IP address associated with Docker Hub by hand. Registry infrastructure uses CDNs and can change addresses frequently. Domain rules are easier to maintain, while IP-CIDR rules may become stale and can accidentally capture unrelated services.
Common Rule Mistake
A rule such as GEOIP,CN,DIRECT or a large private-network rule placed before Docker Hub domains can override your intended proxy route. Inspect the actual matched rule in Clash instead of guessing from the YAML file.
3Resolve DNS and Fake-IP Conflicts
Docker has its own networking behavior, so enabling DNS in Clash does not automatically mean that every Docker lookup is handled by Clash. Depending on the platform and network mode, Docker may ask the host resolver, a Docker embedded DNS server, or a configured external resolver. If that resolver returns an unreachable address, the daemon can fail before its request reaches the proxy.
Clash Verge Rev and Mihomo users can review the active profile’s DNS section. A typical starting point for a desktop environment looks like this:
This is a baseline, not a universal prescription. DNS-over-HTTPS endpoints themselves must be reachable in your network, and a provider’s subscription may already inject compatible settings. Duplicate dns keys, invalid indentation, or an unsupported option can prevent the profile from loading. Always validate and reload the configuration after editing.
Understand fake-ip and Docker
fake-ip mode is useful because Clash maps domain names to synthetic addresses and can apply domain-based rules consistently. However, applications that use hard-coded IP addresses, unusual DNS APIs, or special network namespaces may not behave like a normal browser. Docker containers also have an internal DNS path, so a fake-IP address from the host should not be copied into a container manually.
If Docker begins resolving names incorrectly after fake-ip is enabled, compare the behavior with enhanced-mode: redir-host. This mode is less aggressive and can help isolate compatibility problems. You can also inspect Docker’s current DNS configuration:
On Linux, check whether the host uses systemd-resolved, a local DNS stub, or a manually configured resolver. On Docker Desktop, remember that the daemon runs inside a managed Linux virtual machine, so its resolver is not always identical to the host’s resolver.
Change One Variable at a Time
If you change DNS mode, TUN mode, and daemon proxy settings simultaneously, it becomes difficult to know what fixed the timeout. Test the endpoint after each meaningful change and keep a backup of the working profile.
4Configure the Docker Daemon to Use Clash
This is the step most often missed. Setting an HTTP proxy in your browser or operating-system settings does not necessarily configure the Docker daemon. The daemon performs image pulls, registry authentication, manifest requests, and layer downloads independently. You must provide it with a proxy endpoint that it can reach.
Linux with systemd
First confirm that Clash is listening on an address accessible to the daemon. If Docker and Clash run on the same Linux host, 127.0.0.1:7890 may work. If Clash runs on another machine or inside a separate network namespace, use the appropriate LAN address and ensure the port is allowed by the firewall.
Create a systemd drop-in directory and edit the service configuration:
Add an HTTP and HTTPS proxy. The values below assume Clash exposes an HTTP-compatible mixed port on the local host:
Reload systemd and restart Docker:
Verify that the service received the variables:
Then test a small image:
After a successful test, try the image that originally failed. If the first request succeeds but large layers time out, the issue may be node stability, bandwidth, MTU, or a proxy provider limit rather than basic daemon routing.
Docker Desktop on Windows and macOS
Docker Desktop runs the Docker engine in a managed virtual machine. Configure the proxy in Docker Desktop’s settings rather than assuming that the Windows or macOS system proxy will be inherited. Open the Docker Desktop settings, find the Resources or Proxies section depending on the release, enable the manual proxy option, and enter the Clash HTTP proxy URL, for example http://host.docker.internal:7890 where supported.
The correct hostname depends on the Docker Desktop version and the network arrangement. If host.docker.internal cannot connect to Clash, confirm that Clash allows LAN connections and is listening on the expected interface. Do not expose an unauthenticated proxy port to the public internet. Keep the listener restricted to the local machine or trusted private network.
Do not confuse daemon and container proxies
A daemon proxy controls operations such as docker pull and docker push. A container proxy controls traffic generated by processes inside a running container. They are separate settings. If the image pulls successfully but package installation inside a build fails, configure build arguments or container environment variables separately:
Only use these build arguments when the build actually needs external network access. Avoid baking proxy credentials into image layers, and remove sensitive values from Dockerfiles and build logs.
5Test Pulls and Improve Reliability
Once the daemon proxy is configured, test progressively. Begin with an image that has a small manifest and limited layers. Then test a normal production image, followed by an image with large layers. This sequence separates authentication and routing problems from throughput or long-connection problems.
| Test | What it verifies | Typical conclusion |
|---|---|---|
curl -I through Clash |
Node and proxy endpoint reach Docker Hub | Failure points to Clash, DNS, or the node |
docker pull hello-world |
Daemon can use the configured route | Failure often means the daemon ignored the proxy |
docker login |
Authentication endpoint and token flow | Check auth.docker.io rules if it fails |
| Large image pull | Long-lived connections and bandwidth | Try another node, MTU, or a registry mirror |
Choose a stable node, not only the fastest node
Docker pulls are composed of many requests and can last much longer than opening a web page. A node with excellent browser latency may still have poor sustained throughput, aggressive connection limits, or unstable routing to Docker’s CDN. Test several nodes and compare handshake time, download speed, and whether multiple layers complete without repeated retries.
When a policy group supports automatic testing, use a reasonable interval rather than switching nodes during every request. Frequent switching can interrupt authentication or layer downloads. For production servers, a dedicated, predictable egress path is usually easier to operate than a constantly changing consumer node.
Consider MTU and IPv6 only after basic routing works
Repeated TLS handshake failures or stalled downloads can sometimes be related to an incorrect MTU, especially when TUN mode, a virtual adapter, and another VPN are active at the same time. Disable competing VPN software and test with a single tunnel first. If IPv6 is available locally but the selected proxy path does not support it consistently, temporarily disabling IPv6 in the relevant Clash or Docker environment can help isolate the issue.
Do not permanently reduce MTU or disable IPv6 without testing the impact on other services. These are compatibility experiments, not guaranteed fixes. Record the original values so that you can restore them when the network path changes.
- The selected Clash node can return a response from
registry-1.docker.io. - Clash logs show Docker Hub requests and the expected proxy group.
registry-1.docker.io,auth.docker.io, and related domains are not accidentally routed DIRECT.- The Docker daemon has received
HTTP_PROXYandHTTPS_PROXYvalues. - Docker was restarted after the daemon configuration changed.
- A small image pulls successfully before testing large production images.
6Frequently Asked Questions
Why does Docker pull fail while Chrome works?
Chrome may use a system proxy, an extension, or Clash’s browser-compatible port, while Docker uses a separate daemon process. Unless the daemon or Docker Desktop engine is explicitly configured with a reachable proxy, it may connect directly. Check the Clash connection log during docker pull; if no registry request appears, the browser and Docker are using different network paths.
Should Docker use the HTTP port or the SOCKS5 port?
Docker daemon proxy settings commonly use an HTTP proxy URL, including for HTTPS destinations through the HTTP CONNECT method. Use Clash’s HTTP or mixed port unless your Docker environment specifically supports a SOCKS5 proxy. Do not write socks5:// in a setting that expects an HTTP proxy, because the daemon may reject it or fail silently.
Why is the response code 401 when I test Docker Hub?
Docker Hub’s registry API normally requires a token, so an unauthenticated request to /v2/ often returns 401 Unauthorized. This confirms that the endpoint answered. Proceed to test docker login and docker pull. If login fails, make sure both the registry domain and auth.docker.io are routed through the same reliable proxy policy.
Is TUN mode required for Docker?
No. TUN mode can capture applications that do not honor proxy variables, but it is not automatically the best solution. A daemon-level HTTP proxy is more explicit and easier to audit for Docker Hub operations. Use TUN mode when the daemon cannot be configured directly or when other non-proxy-aware programs also need routing, and avoid running multiple virtual network adapters at the same time.
Once Docker Hub works through a verified Clash route, keep the configuration simple: use a stable node, explicit registry rules, a tested DNS strategy, and a daemon proxy that is easy to inspect. This approach is more dependable than repeatedly toggling Global Mode and hoping that Docker inherits browser behavior.