Skip to main content

Troubleshooting Docker Hub Pull Failures on Aliyun ECS

Problem Background​

When pulling Docker Hub images directly from an Aliyun ECS instance, common symptoms include:

  • docker pull is extremely slow
  • Timeouts during pull
  • Repeated retries still fail
  • Some images work fine on local networks but cannot download reliably from cloud servers

Most of the time, this is not Docker itself being broken. The issue is that the network path to Docker Hub is slow or unstable.

A common fix recommended by Aliyun is to obtain an ACR mirror accelerator address for your account, then configure it in Docker or Containerd.

Official documentation:

Bottom Line​

If you just want to get your machine running and stop docker pull from hanging, the most practical approach is:

  1. Get your own mirror accelerator address from the Aliyun Container Image Service (ACR) console
  2. Write that address into Docker's daemon.json
  3. Restart Docker
  4. Confirm it works with docker info and an actual pull

Important Limitation​

There is a critical point in the Aliyun official docs:

  • ACR image mirroring has stopped syncing the latest images
  • If you depend on the latest tag, the image you pull may not be the newest version
  • If a particular image always fails to pull, or you explicitly need the latest version, this approach may not be reliable

Aliyun's suggested alternatives are:

  • Subscribe to overseas source images within ACR
  • Use Global Acceleration (GA) to directly speed up access to overseas sources

So this guide is best suited for:

  • Personal development
  • Temporary troubleshooting
  • Quickly restoring Docker Hub pull capability

For production environments, do not rely entirely on this approach for stable Docker Hub access.

Step 1: Get the ACR Mirror Accelerator Address​

Follow the official docs path to reach the console:

  1. Log in to the Aliyun Container Image Service console
  2. Navigate to: Image Tools > Image Accelerator
  3. Copy the accelerator address for your account

The address typically looks like:

https://<your-id>.mirror.aliyuncs.com

Step 2: Configure the Docker Image Accelerator​

If you are using a recent Docker version, editing /etc/docker/daemon.json is enough.

{
  "registry-mirrors": ["https://<your-id>.mirror.aliyuncs.com"]
}

Actual Commands​

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": ["https://<your-id>.mirror.aliyuncs.com"]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

Verify It Works​

docker info
docker pull ubuntu:22.04

Check whether Registry Mirrors appears in the docker info output, then confirm that actual pulls are back to normal.

If You Are Using Containerd​

The official docs also cover Containerd. The core idea is:

  1. Confirm that /etc/containerd/config.toml has config_path configured
  2. Clean up old mirror configuration to avoid conflicts
  3. Create docker.io/hosts.toml
  4. Restart Containerd

A common configuration looks like this.

1. Confirm config_path​

[plugins."io.containerd.grpc.v1.cri".registry]
  config_path = "/etc/containerd/certs.d"

2. Create hosts.toml​

File path:

/etc/containerd/certs.d/docker.io/hosts.toml

File content:

server = "https://registry-1.docker.io"

[host."https://<your-id>.mirror.aliyuncs.com"]
  capabilities = ["pull", "resolve", "push"]

3. Restart and Troubleshoot​

sudo systemctl restart containerd
sudo journalctl -u containerd

If startup fails, check first whether old mirror configuration is still lingering in config.toml.

How I Recommend Using This​

In practice, treat this approach as "restore availability first", not "permanently solve Docker Hub issues".

A more sustainable approach:

  • Pin base images to explicit versions; do not depend on latest
  • Pre-cache or sync frequently used images to your own registry
  • Minimize direct dependency on Docker Hub in production

Minimum Viable Troubleshooting Flow​

If you hit "Docker Hub pulls stuck on Aliyun" again in the future, follow this sequence:

  1. Confirm the machine itself has working internet access
  2. Go to the ACR console and copy the mirror accelerator address
  3. Configure /etc/docker/daemon.json
  4. Restart Docker
  5. Run docker info
  6. Pull a small image to verify, e.g. ubuntu:22.04
  7. If it still fails, consider switching to ACR overseas source subscription or GA

References​