Docker Pull Stuck? Route Docker Hub and Registry Mirrors in Clash (2026)

1. Why docker pull Breaks Under Split Routing

Most developer machines already run a proxy client for browsers and IDEs. Docker, however, speaks the OCI distribution protocol to a small set of high-value hostnames. When those names are treated as “just more HTTPS,” broad keyword rules or continent-level shortcuts mis-classify individual connections. A manifest fetch might traverse a clean path while a blob download rides a different policy because an anycast IP matched an unexpected rule type. The engine retries, opens parallel connections, and surfaces a bland timeout because user interfaces rarely show which hostname in the chain stalled.

The fix is boring and effective: enumerate the names you truly use, place explicit DOMAIN-SUFFIX rows in sane order, and assign them to a purpose-built group—call it “Docker+Registry”—with a stable exit. This is the same engineering you apply to fragile SaaS panels; registry mirror setups only add more suffixes you must admit into YAML intentionally, not hide behind hope and a single catch-all.

Treat subscriptions as untrusted for specialty paths. Community rule providers are excellent for everyday browsing but rarely version the exact Docker Hub edges your daemon touches this quarter. Maintain a small override file you understand, merge it deterministically, and re-validate after every profile import—patterns we reinforce in merging multiple Clash profiles.

2. Symptoms That Hint at Policy, Not “Bad Images”

Network-policy failures masquerade as registry bugs. Watch for pulls that freeze after the manifest prints but before layers complete, intermittent “i/o timeout” strings, or TLS errors that mention unexpected EOF. Often a plain curl to a marketing page works while docker pull fails because the registry client insists on HTTP/2, different cipher suites, or longer idle periods than your shortcut rule anticipated.

Before swapping nodes, collect three facts from mihomo logs: the hostname, the outbound group, and whether repeated attempts oscillate between groups. Oscillation almost always means order or cache—not bandwidth. Stable groups with terrible latency point to path health; consider url-test or fallback inside the dedicated group using endpoints meaningful to you, not generic homepages, following our latency failover guide.

Separate entitlement issues from transport. Private repos, revoked tokens, and rate limits still happen. This article clears the path in front of legitimate anonymous or token-based Hub pulls; it does not bypass provider policy.

3. Traffic Map: Hub, Auth, CDN, and Your Mirrors

Use the following as a starter set you refine from live logs—not an eternal guarantee of Docker’s infrastructure. Public pulls commonly touch registry-1.docker.io for the registry API, auth.docker.io for authentication helpers, hub.docker.com when tooling hits the web API, and various *.docker.com hosts including CDN-style edges such as production.cloudflare.docker.com for blob delivery paths seen in many regions. Your organization may also allow-list docker.io redirects and additional sandbox domains during experiments.

When you configure a registry mirror—sometimes marketed as an image accelerator—the Engine resolves and trusts that mirror’s hostname as another HTTPS registry. Examples vary by provider and country; you might see university mirrors, vendor-hosted caches, or regional cloud front-ends. Insert the exact mirror hostname from your /etc/docker/daemon.json (or the Windows/macOS JSON equivalent) into Clash rules beside Hub entries. Do not assume a keyword rule “covers mirrors,” because innocent substrings can drag unrelated finance or news traffic into a dev-only group.

Air-gapped and hybrid setups may add internal registries such as harbor.example.local or cloud vendor endpoints. Route internal names explicitly; never accidentally force them through a public exit because DOMAIN-KEYWORD,docker seemed convenient. If HTTPS SNI does not match naive assumptions, revisit sniffer settings after baseline DNS alignment using the HTTPS sniffer guide—but only once plain domain rows are truthful.

4. Policy Groups: One Consistent Exit for Image Layers

Create a dedicated group for distribution traffic so you do not confuse it with streaming or chat groups that rotate nodes aggressively. Image pull benefits from coherence: the same metropolitan egress for manifest, auth, and blob legs reduces spurious TLS surprises when middleboxes treat connection affinity oddly across regions.

Rule order still dominates outcomes. Place explicit registry suffix rows above regional GEOIP shortcuts, MATCH, and keyword catch-alls that “felt fine” for browsing. If an IP-based rule wins because a CDN shifted anycast allocation, you will waste hours blaming node quality instead of moving two YAML lines. The general discipline is summarized in our rule routing reference; this article applies that grammar to the container distribution plane.

If you import huge community lists, consolidate overrides into one reviewed merge. Duplicate contradicting rows produce half-downloaded layers—worse than a clean, slow path because manifests sometimes succeed where blobs do not, leaving broken intermediate states on disk.

5. Example YAML: Docker Registry–Friendly Rules

The snippet below is illustrative. Replace group names, extend suffixes with mirror hosts from your real daemon.json, and insert the block before broad direct or regional shortcuts.

proxy-groups:
  - name: 🐳 Docker+Registry
    type: select
    proxies:
      - US-Images-Stable
      - JP-LowLoss
      - DIRECT

rules:
  - DOMAIN-SUFFIX,docker.io,🐳 Docker+Registry
  - DOMAIN-SUFFIX,docker.com,🐳 Docker+Registry
  # Optional narrow rows first if you prefer minimal blast radius:
  # - DOMAIN,registry-1.docker.io,🐳 Docker+Registry
  # - DOMAIN,auth.docker.io,🐳 Docker+Registry
  # Mirror examples — replace with your actual daemon.json hosts:
  # - DOMAIN-SUFFIX,example-mirror.edu,🐳 Docker+Registry
  # - DOMAIN-SUFFIX,registry.example.corp,🐳 Docker+Registry
  # ... GEOIP and MATCH follow ...

6. daemon.json Mirrors vs Proxy Rules: Two Knobs

Linux daemons and Docker Desktop both let you declare registry mirror endpoints to reduce dependence on a single geographic path. That is orthogonal to Clash policy: mirrors answer “which HTTPS server speaks the registry API,” while Clash answers “which IP path reaches that server.” A mirror that is only reachable through a specific egress requires the mirror hostname in your YAML, not merely JSON on disk.

Conversely, if a mirror is engineered for domestic ISPs and behaves poorly through an overseas SOCKS exit, forcing it into the same group as registry-1.docker.io may be wrong. Split mirrors and Hub into sibling groups only when your measurements justify the complexity; otherwise prefer one group and accept coordinated DIRECT or proxy for both. Whatever you choose, make it explicit so flows never flip between retries.

For build-time pulls inside CI agents, remember proxies configured at the shell layer do not automatically rewrite daemon traffic. Pair this routing guide with host-level environment strategies from host proxy and gateway setups when builders and daemons must share one operational story.

7. DNS, fake-ip, and Where Resolvers Actually Run

Routing YAML is useless if names never traverse the resolver stack you think they do. Operating systems, browsers with secure DNS, and hypervisors can all resolve registry-1.docker.io outside Clash, especially when fake-ip is enabled but downstream clients still query public resolvers directly. The symptom is classic: “rules look perfect” while logs show unexpected IP families or policies not engaging.

Read fake-ip versus redir-host with registry workloads in mind. Some teams standardize on redir-host for developer machines to reduce cognitive load; others keep fake-ip but document mandatory per-OS toggles that stop silent DoH. Either can work; inconsistency cannot.

Corporate laptops often ship split tunnel VPN clients that intercept DNS for “trusted domains.” If those products fight Clash for port 53 or push bespoke resolver lists, normalize ownership: either the enterprise agent resolves known internal registries and yields public names to Clash, or Clash becomes the single resolver—pick one architecture and test docker pull after every endpoint security upgrade.

8. TLS, SNI, and Long Downloads

Registry clients maintain long-lived connections for layer downloads. Middleboxes that interfere with TLS renegotiation or HTTP/2 flow control show up as stalls mid-gigabyte, not immediate failures. If failures cluster on HTTP/3 while TCP behaves, run a controlled test disabling QUIC in a disposable profile before you chase node myths—mirroring guidance from our MCP tooling routing article for developer stacks.

QUIC aside, verify that inspection appliances or captive portals are not breaking pinned expectations. Enterprise HTTPS inspection can poison trust stores inside VMs while the host browser still works, yielding timeouts that resemble “Docker Hub is down.” Compare Engine behavior on a clean network segment before rewriting Clash.

Subscription update channels deserve mention: if your Clash profile itself cannot refresh because TLS to the panel is flaky, your carefully crafted registry overrides never reach disk. When panels fail intermittently, walk subscription TLS and DNS triage first so policy drift does not masquerade as registry outage.

9. Verification Checklist

After updates to mirrors, subscriptions, or OS networking stacks, walk this list before opening a fire incident:

When every box passes but pushes still fail, return to repository permissions, token scopes, and registry quotas—technology clears the path; it does not invent credentials.

10. Frequently Asked Questions

11. Closing Thoughts

Reliable image pull is a routing problem dressed up as DevOps theater. Generic “VPN on, problem solved” clients optimize for entire-device tunnels, not fine-grained trust in registry-1.docker.io versus a regional registry mirror. Older HTTP-only helper tools also struggle when modern engines lean on HTTP/2, long-lived TLS sessions, and CDN bursts that need consistent egress planning. Clash Meta earns its place on developer workstations because you can line up explicit domain rows, keep DNS honest with mihomo, and prove—using logs—which leg of a failed docker pull wandered into the wrong policy group. That observability beats toggling opaque modes when deadlines loom.

When you are ready to standardize on a maintained client that tracks the Meta ecosystem, start from our download center, then layer registry overrides, mirror hostnames, and DNS calibration in that order. → Download Clash free and keep Docker Hub pulls predictable