Home / Docker / Docker Image Pull Timeout

Docker

Docker Image Pull Timeout

Resolve timeout errors when pulling Docker images from registries

Published: Nov 19, 20257 min readBy FixWikiHub Editorial Team

Abstract illustration for a troubleshooting knowledge base category.

Introduction

When attempting to pull a Docker image from a registry (Docker Hub, private registry, etc.), the operation times out. This can occur during manifest downloads, layer pulls, or authentication. The failure prevents you from getting the images needed to run containers.

Symptoms

```bash $ docker pull nginx:latest Error: Get https://registry-1.docker.io/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

$ docker pull myapp:latest Error: failed to register layer: Error processing tar file(exit status 1): unexpected EOF

$ docker pull alpine Error: error pulling image configuration: Get https://registry-1.docker.io/v2/library/alpine/blobs/sha256/...: dial tcp: lookup registry-1.docker.io: no such host

$ docker pull gcr.io/myproject/myimage Error: denied: Permission denied for "myimage" from gcr.io/myproject ```

Common Causes

1.Slow network connection: Large images take too long to download
2.Firewall blocking: Corporate or cloud firewalls blocking registry access
3.DNS resolution issues: Can't resolve registry hostname
4.Proxy configuration: Missing or incorrect proxy settings
5.Registry rate limits: Docker Hub rate limiting pulls
6.Authentication failures: Invalid or expired credentials
7.SSL/TLS issues: Certificate validation failures
8.Registry unavailable: Registry is down or unreachable

Step-by-Step Fix

Step 1: Test Network Connectivity

Verify you can reach the registry:

```bash # Test basic connectivity to Docker Hub ping -c 4 registry-1.docker.io

# Test HTTPS connection curl -I https://registry-1.docker.io/v2/

# Test with verbose output curl -v https://registry-1.docker.io/v2/

# Test DNS resolution nslookup registry-1.docker.io

# Test specific port connectivity nc -zv registry-1.docker.io 443

# Check if behind firewall telnet registry-1.docker.io 443 ```

Step 2: Configure Docker Timeout

Increase Docker client timeout:

```bash # Set timeout environment variable export DOCKER_CLIENT_TIMEOUT=120 export COMPOSE_HTTP_TIMEOUT=120

# Or in systemd service (Linux) sudo systemctl edit docker.service ```

Add: ``ini [Service] Environment="DOCKER_CLIENT_TIMEOUT=120" Environment="COMPOSE_HTTP_TIMEOUT=120"

bash

# Reload and restart
sudo systemctl daemon-reload
sudo systemctl restart docker

Configure in Docker config: ``bash # Edit Docker daemon config sudo nano /etc/docker/daemon.json

json

{
  "max-concurrent-downloads": 1,
  "max-download-attempts": 5
}

bash

# Restart Docker
sudo systemctl restart docker

Step 3: Configure Proxy

If you're behind a corporate proxy:

```bash # Create Docker systemd directory sudo mkdir -p /etc/systemd/system/docker.service.d

# Create proxy config sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf ```

Add proxy configuration: ``ini [Service] Environment="HTTP_PROXY=http://proxy.company.com:8080" Environment="HTTPS_PROXY=http://proxy.company.com:8080" Environment="NO_PROXY=localhost,127.0.0.1,.company.com"

```bash # Reload systemd sudo systemctl daemon-reload

# Restart Docker sudo systemctl restart docker

# Verify proxy settings systemctl show --property=Environment docker ```

Configure Docker client proxy: ``bash # Edit Docker client config nano ~/.docker/config.json

json

{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.company.com:8080",
      "httpsProxy": "http://proxy.company.com:8080",
      "noProxy": "localhost,127.0.0.1,.company.com"
    }
  }
}

Step 4: Handle Docker Hub Rate Limits

Docker Hub has rate limits for anonymous and authenticated pulls:

```bash # Check current rate limits TOKEN=$(curl -s "https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/ratelimitdemo:pull" | jq -r .token) curl -s -H "Authorization: Bearer $TOKEN" https://registry-1.docker.io/v2/ratelimitpreview/ratelimitdemo/manifests/latest -I | grep -i ratelimit

# Authenticate with Docker Hub docker login

# Pull with authentication docker pull nginx ```

Use authenticated pulls in CI/CD: ```yaml # GitHub Actions - name: Login to Docker Hub uses: docker/login-action@v2 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }}

name: Pull image
run: docker pull nginx
`

Use alternative registries or mirrors: ``bash # Configure Docker mirror sudo nano /etc/docker/daemon.json

json

{
  "registry-mirrors": [
    "https://mirror.gcr.io",
    "https://registry.docker-cn.com"
  ]
}

Step 5: Fix DNS Issues

If DNS resolution fails:

```bash # Check DNS resolution nslookup registry-1.docker.io dig registry-1.docker.io

# Configure Docker to use specific DNS sudo nano /etc/docker/daemon.json ```

json

{
  "dns": ["8.8.8.8", "8.8.4.4", "1.1.1.1"]
}

```bash # Restart Docker sudo systemctl restart docker

# Test DNS in container docker run --dns=8.8.8.8 alpine nslookup registry-1.docker.io ```

Step 6: Fix SSL/TLS Issues

Handle certificate validation problems:

bash

# For insecure registries (not recommended for production)
sudo nano /etc/docker/daemon.json

json

{
  "insecure-registries": ["my-registry.local:5000"]
}

```bash # Restart Docker sudo systemctl restart docker

# For self-signed certificates, add to trusted certs sudo mkdir -p /etc/docker/certs.d/my-registry.local:5000 sudo cp my-ca.crt /etc/docker/certs.d/my-registry.local:5000/ca.crt

# Restart Docker sudo systemctl restart docker ```

For corporate SSL inspection: ```bash # Add corporate CA to system trust store sudo cp corporate-ca.crt /usr/local/share/ca-certificates/ sudo update-ca-certificates

# Restart Docker sudo systemctl restart docker ```

Step 7: Authenticate with Private Registries

For private registry access:

```bash # Docker Hub login docker login

# Login to specific registry docker login registry.company.com

# Login with credentials docker login -u username -p password registry.company.com

# Login using token echo "my-token" | docker login -u username --password-stdin registry.company.com

# Check stored credentials cat ~/.docker/config.json ```

Configure in docker-compose.yml: ``yaml services: app: image: registry.company.com/myapp:latest

bash

# Docker Compose will use stored credentials
docker-compose pull

Step 8: Pull with Retry and Debug

Implement retry logic and debug pulling:

```bash # Pull with retry logic for i in {1..5}; do docker pull nginx && break || sleep 30 done

# Pull specific platform image docker pull --platform linux/amd64 nginx

# Pull with debug DOCKER_DEBUG=1 docker pull nginx

# Pull specific digest (immutable reference) docker pull nginx@sha256:abc123...

# Pull by tag docker pull nginx:1.23

# Pull all tags docker pull --all-tags nginx ```

Step 9: Use Layered or Alternative Pulling

For large images or slow connections:

```bash # Pull with fewer concurrent downloads docker pull --quiet nginx

# Save bandwidth by pulling base layers separately docker pull alpine:latest docker build --cache-from alpine:latest -t myapp .

# Use skopeo for robust pulling skopeo copy docker://docker.io/library/nginx:latest docker://localhost:5000/nginx:latest

# Pull via docker save/load on different machine # On machine with good connection: docker pull nginx docker save nginx -o nginx.tar

# Transfer file, then on target machine: docker load -i nginx.tar ```

Verification

Test that image pulls work correctly:

```bash # Test basic pull docker pull nginx:latest

# Verify image exists docker images nginx

# Run container from pulled image docker run --rm nginx nginx -v

# Check pull times docker images --format "{{.Repository}}:{{.Tag}} {{.CreatedAt}}"

# Pull and run in one command docker run --rm -it alpine:latest /bin/sh

# Test authenticated pull docker logout docker login docker pull your-private-image ```

Image pulls should now complete without timeout errors.

[Fix docker build cache invalidated unnecessary layers Issue in Docker-Errors](docker-build-cache-invalidated-unnecessary-layers)
[Fix Docker Build Cache Invalidation Optimization Issue in Docker](docker-build-cache-invalidation-optimization)
[Fix docker build context slow large files Issue in Docker-Errors](docker-build-context-slow-large-files)
[Fix docker build multi stage copy from not found Issue in Docker-Errors](docker-build-multi-stage-copy-from-not-found)
[Fix docker buildkit export local tar layer missing Issue in Docker-Errors](docker-buildkit-export-local-tar-layer-missing)

Was this guide helpful?

Related search paths

People also search for

If the symptom is close but not identical, these search paths usually surface the right neighboring fixes faster than scrolling the full archive.

Docker Image Pull Timeout Docker Image Pull Timeout Docker Docker Image Pull Timeout troubleshooting Docker Image Pull Timeout fix Resolve timeout errors when pulling Docker images from registries Docker Resolve timeout errors when pulling Docker images from registries

Explore Related Topics

Browse Guides from Other Categories

Discover troubleshooting guides from related categories to expand your knowledge.

FAQ

Docker Troubleshooting FAQs

Common questions about troubleshooting and preventing similar issues

How do I know if this docker-errors troubleshooting guide applies to my situation?

This guide is designed for docker-errors issues. If you're experiencing similar symptoms described in the article, follow the step-by-step instructions. Start with the most common causes and work through the diagnostic process.

Is it safe to follow these docker-errors troubleshooting steps?

Yes, all steps are designed to be safe and non-destructive. We recommend creating backups before making significant changes and testing each step before proceeding to the next.

How long does it typically take to resolve this type of docker-errors issue?

Most docker-errors issues can be resolved within 30 minutes to 2 hours, depending on the complexity and root cause. Follow the troubleshooting flow to identify and fix the problem efficiently.

How can I prevent this docker-errors issue from happening again?

Regular maintenance, monitoring, and following best practices for docker-errors configuration can help prevent recurrence. Consider implementing automated checks and alerts for early detection.

Written by

FixWikiHub Editorial Team

Our editorial team consists of experienced DevOps engineers, systems administrators, and cloud architects with hands-on experience in production environments across AWS, Azure, GCP, and on-premises infrastructure.

Every guide undergoes technical review for accuracy and is updated when software versions, commands, or best practices change.

Last updated: Nov 19, 2025

About our team

Important Notice

Disclaimer & Safety Guidelines

The troubleshooting steps in this guide are provided for educational and informational purposes. Before applying any changes to production systems:

Test in a staging environment first — Always verify commands and configurations in a non-production environment before deploying to live systems.
Create backups — Ensure you have current backups of databases, configurations, and critical files before making changes.
Understand the impact — Review how each step may affect your specific environment, dependencies, and users.
Consult official documentation — This guide supplements, but does not replace, official vendor documentation and best practices.

FixWikiHub is not responsible for any damages arising from the use of this content. See our Terms of Use for more information.

Resources

Official Documentation & Further Reading

For authoritative information, consult the official documentation for the technologies discussed in this guide. Our troubleshooting content supplements, but does not replace, vendor documentation.

AWS Documentation — Official Amazon Web Services guides and API references
Kubernetes Documentation — Official Kubernetes documentation
Nginx Documentation — Official Nginx web server documentation
Apache Documentation — Official Apache HTTP Server documentation
Docker Documentation — Official Docker container documentation

Docker Image Pull Timeout

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Step 1: Test Network Connectivity

Step 2: Configure Docker Timeout

Step 3: Configure Proxy

Step 4: Handle Docker Hub Rate Limits

Step 5: Fix DNS Issues

Step 6: Fix SSL/TLS Issues

Step 7: Authenticate with Private Registries

Step 8: Pull with Retry and Debug

Step 9: Use Layered or Alternative Pulling

Verification

Related Articles

People also search for

Share this guide

More Docker Troubleshooting Guides

Browse Guides from Other Categories

Docker Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading