The Problem: Why Your Pull is Timing Out
You type docker pull, hit Enter, and wait. Instead of the usual progress bars, the terminal stares back for a full 60 seconds. Finally, it gives up with a timeout message:
Error response from daemon: Get "https://registry-1.docker.io/v2/": context deadline exceeded
Essentially, Docker's internal stopwatch hit zero. It tried to reach the official registry, but the network didn't respond fast enough. This isn't usually a bug in Docker itself. Instead, think of it as a "busy signal" caused by a corporate firewall, a sluggish DNS, or a misconfigured network bridge.
Debug Process: Isolate the Bottleneck
Don't start changing settings blindly. First, let's find exactly where the signal is dropping. Run these checks to pinpoint the culprit.
1. Check Basic Connectivity
Can your machine see the registry at all? Test the connection to the Docker Hub API:
ping registry-1.docker.io
Look at the time in milliseconds. If you see latency over 500ms, your connection is too slow for Docker's default handshake. If you get "unknown host," your system is completely blind to the domain.
2. Test DNS Speed
ISP-provided DNS servers are notorious for being slow or intermittently blocking registry domains. Use nslookup to see how long resolution takes:
nslookup registry-1.docker.io
If this command takes more than 2 seconds to return an IP address, Docker will almost certainly time out before the download even begins.
Reliable Fixes for 'Context Deadline Exceeded'
Solution 1: Switch to a Faster DNS
The most effective fix is pointing Docker toward Google (8.8.8.8) or Cloudflare (1.1.1.1). You don't need to change your entire OS configuration; you can apply this specifically to the Docker daemon.
Open or create /etc/docker/daemon.json and add the DNS array:
{
"dns": ["1.1.1.1", "8.8.8.8"]
}
Apply the changes by restarting the service:
sudo systemctl restart docker
Solution 2: Configure Proxy Settings
If you're working behind a corporate proxy, Docker needs to be told explicitly how to route traffic. It doesn't automatically inherit your shell's EXPORT variables. You must configure the systemd service directly.
- Create a dedicated config directory:
sudo mkdir -p /etc/systemd/system/docker.service.d
- Create `http-proxy.conf` with your specific proxy details:
```
[Service]
Environment="HTTP_PROXY=http://proxy.yourcompany.com:8080/"
Environment="HTTPS_PROXY=http://proxy.yourcompany.com:8080/"
Environment="NO_PROXY=localhost,127.0.0.1"
- Reload the configuration and restart Docker:
sudo systemctl daemon-reload sudo systemctl restart docker
### Solution 3: Fix MTU Mismatches (VPN Users)
Are you using a VPN? Your network packets might be too large for the encrypted tunnel. When packets are too big, they get dropped, leading to mysterious hangs at the start of a download.
Standard MTU is 1500. Try dropping it to 1450 in your `daemon.json` to give the packets more "breathing room":
{ "mtu": 1450 }
### Solution 4: Use a Local Registry Mirror
If your geographic region has poor connectivity to Docker Hub's US-based servers, use a closer mirror. This bypasses long-distance routing issues. Add this to your `daemon.json`:
{ "registry-mirrors": ["https://mirror.gcr.io"] }
## Verification: Testing the Fix
Check your work by pulling a tiny image. Don't waste time pulling a 500MB database; use `alpine`, which is only about 5MB:
docker pull alpine:latest
If the layers download immediately, the bottleneck is gone.
## Pro-Tip: Avoid Network Overlaps
Sometimes timeouts happen because Docker's internal network (like 172.17.0.0/16) overlaps with your office's actual IP range. When planning your infrastructure, using an [IP Subnet Calculator](https://toolcraft.app/en/tools/developer/ip-subnet-calculator) helps you pick safe ranges that won't conflict with your local routing. This prevents those "ghost" connectivity issues that are a nightmare to debug.
## Quick Recap
- **DNS is the prime suspect:** Slow name resolution causes 90% of these errors.
- **Daemon JSON is your friend:** Most network fixes happen in `/etc/docker/daemon.json`.
- **Proxies are separate:** Docker runs as a service, so it needs its own systemd proxy config.
- **MTU matters for VPNs:** If small pings work but big pulls fail, lower your MTU to 1400 or 1450.