Problem: docker pull fails on campus/home network (connection reset / dead mirror lists) —— Trove problem library

What you will run into

On campus/home networks (no proxy), docker pull reports ERROR: Get "https://registry-1.docker.io/v2/": ... connection reset by peer, or the image never downloads.

Following old tutorials about mirror accelerators makes it worse (no such host) — because most accelerator lists floating around the web are dead; don't copy them blindly.

Why this happens

The official Docker Hub registry (registry-1.docker.io) has no stable acceleration for CN networks; direct connections are frequently dropped at the network layer (connection reset / timeout are the same family).

Accelerators are third-party services that die and change: measured 2026-08-29, of 9 common accelerators only 1panel.live (200), daocloud (401), xuanyuan (401), 1ms (401), rat.dev (302) were usable;

dockerproxy.cn / sjtug / dockerpull.org / ustc were all dead (000) — "old lists from the web" and "outdated mirror configs" are the second biggest failure source (DNS no such host).

docker pull follows "CLI → registry-1.docker.io → CDN redirects for each layer blob": when domestic egress to the registry hostname is unstable, connections get reset/timed out at the transport layer — the error has nothing to do with your command.

A mirror accelerator is essentially a third-party registry proxy: its availability depends on its operator, and mirrors die, change domains, or get rate-limited — which is why "stale lists from tutorials + outdated mirror configs" are the second source of failure (DNS no such host).

Deterministic path: layer first — curl -I https://registry-1.docker.io/v2/ tells you about direct connectivity;

when probing accelerators, 401/302 does not mean dead (it may be a normal auth-required response), while 000 or DNS no such host means truly dead;

after configuring, you must confirm Registry Mirrors actually took effect via docker info — configuring without verifying is not configuring.

Step by step

1. Confirm the failure mode — Required

• connection reset by peer / i/o timeout on the direct registry → connection dropped at network layer;
• no such host / DNS resolution failure → the configured accelerator domain is dead.

2. Write in measured working mirrors — Required

sudo tee /etc/docker/daemon.json >/dev/null <<'EOF'
{
  "registry-mirrors": [
    "https://docker.1panel.live",
    "https://docker.m.daocloud.io"
  ]
}
EOF

Back up the original config first (the quick-fix command above already includes the backup).

Accelerators change; once the configured one stops working, run another measurement round (curl -o /dev/null -s -w '%{http_code}' https://<mirror-domain>/v2/; 401/200/302 = usable, 000 = dead).

3. Restart and verify — Required

sudo service docker restart
docker pull hello-world

Download complete / Pull complete means success (measured: after updating the config the pull succeeded, exit 0).

4. Errors during pull/extract (docker >= 23.0) — Required

Some mirror sites connect but fail during pull/extract; enable containerd native image storage: add "features": { "containerd-snapshotter": true } to daemon.json and restart (from a supplementary article;

this branch was not reproduced on this machine, not measured).

5. Long-term / enterprise options — Required

Self-host a registry, or pull through an HTTP proxy and import offline; CI can use an overseas build machine that can reach Hub.

How to confirm it works

docker pull hello-world && docker run --rm hello-world

A successful pull and run means it's fixed. Measured: direct registry-1.docker.io:443 curl timed out after 12s (Connection timed out, exit 28); after updating daemon.json (1panel.live + daocloud) docker pull hello-world succeeded.

Other environments

Symptom

docker pull fails in one of three common forms:

# Form 1: direct connection to Docker Hub reset (network layer)
Error response from daemon: Get "https://registry-1.docker.io/v2/": read tcp ...:443: read: connection reset by peer
# or: hangs after "Using default tag: latest" with no progress / timeout

# Form 2: configured mirror is dead (DNS layer)
Error response from daemon: failed to resolve reference "docker.io/library/xxx:latest":
failed to do request: Head "https://<mirror>/v2/...": dial tcp: lookup <mirror> on ...:53: no such host

Most common on networks inside China; the error may involve IPv6 addresses (IPv6 connection reset); retrying sometimes passes; worked before but suddenly fails one day (mirror shut down); or a fresh docker setup used a mirror list copied from an outdated tutorial.

Same family but different root cause (don't fight the network on this page):

• manifest for xxx not found / manifest unknown -> image or tag does not exist, see docker-manifest-not-found;
• no space left on device (pull/extract stage) -> under WSL the common truth is a full host drive, see wsl-no-space-left;
• Pull stops halfway / repeated timeouts: network jitter — just re-run docker pull; already-downloaded layers are reused by digest and skipped automatically, no cache cleaning or rmi needed.

Cause

Docker Hub's official registry registry-1.docker.io is not directly reachable from networks inside China (connection reset / timeout). That is why "registry mirrors" became standard practice — but after Docker Hub tightened its policies in 2024, many public mirrors have shut down: the USTC mirror docker.mirrors.ustc.edu.cn, SJTU docker.mirrors.sjtug.sjtu.edu.cn, dockerproxy.cn, etc. were all dead in our 2026-08-29 test (DNS doesn't even resolve). Copying old mirror lists from the web is a top failure cause — mirrors have a lifespan; always test before configuring.

Solution

1. Test first, then configure a working mirror (core): check with curl -s -o /dev/null -w "%{http_code}" --max-time 8 https://<mirror>/v2/ — 200/401/302 means reachable (401 is a normal unauthenticated registry response), 000 or DNS failure means dead. Verified working on 2026-08-29 (campus network): docker.1panel.live (200), docker.m.daocloud.io (401), docker.xuanyuan.run (401), docker.1ms.run (401), hub.rat.dev (302).
2. Write daemon.json and restart: set registry-mirrors in /etc/docker/daemon.json (list several as fallbacks; docker tries them in order), then sudo systemctl restart docker (or sudo service docker restart). Example:

{
  "registry-mirrors": [
    "https://docker.1panel.live",
    "https://docker.m.daocloud.io"
  ]
}

1. Verify with a real pull: docker pull hello-world succeeding means the fix is live.
2. Pull/extraction-stage errors (docker >= 23.0): if the mirror is reachable but extraction fails, enable containerd's native image store: add "features": { "containerd-snapshotter": true } to daemon.json and restart (from a supplementary article; not reproduced here because pulls already succeed).
3. Long-term / enterprise: run your own registry, or pull through an HTTP proxy and export offline; use a build machine outside the blocked network in CI.

Related canonicals

Read in order: precondition -> this page -> same root / variant family:

• Precondition (rule out first): Cannot connect to the Docker daemon — when the daemon is down, pull reports a connection error, not a network problem
• Same root (one network-layer cause, CN mirror family):
• GitHub direct connection slow/fails (image/Release asset downloads dropped)
• pip install timeout/slow (CN mirror family)
• npm install slow/hang (CN mirror family)
• Go module fetch slow/timeout (CN mirror family)
• ollama pull stuck/timeout (registry direct-connect unstable -> switch source)
• DNS resolution fails inside containers (no such host is DNS-layer: host daemon side vs inside container)
• Variant family (other pull failure forms, different root cause):
• Image or tag does not exist (manifest unknown / not found)
• WSL reports No space left (pull/extract ENOSPC, WSL host drive full)