How to fix context deadline exceeded in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 744 views

The 'context deadline exceeded' error occurs when a Docker operation fails to complete within the allotted timeout period. This typically indicates network connectivity issues, DNS resolution failures, slow registry responses, or Docker daemon problems.

Quick fix

Fixes context deadline exceeded

# Test connectivity to Docker Hub
curl -I https://registry-1.docker.io/v2/

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

# Check for latency issues
ping -c 5 registry-1.docker.io
  1. Verify network connectivity to Docker registry
  2. Configure DNS settings
  3. Increase timeout for Docker Compose
  4. Manually pull images before deployment
docker — error
# Test connectivity to Docker Hub
curl -I https://registry-1.docker.io/v2/
# Test DNS resolution
nslookup registry-1.docker.io
# Check for latency issues
ping -c 5 registry-1.docker.io
context deadline exceeded

What this error means

The "context deadline exceeded" error is a timeout message originating from Go's context package, which Docker uses internally. When you see this error, it means that a Docker API request or network operation took longer than the configured timeout and was cancelled. This error commonly appears during operations like pulling images from a registry, pushing images, or when the Docker daemon fails to respond in time. The "deadline" refers to the maximum time allowed for an operation to complete, and "exceeded" means that time limit was reached before the operation finished. The error is often a symptom of underlying network or infrastructure issues rather than a problem with Docker itself. It frequently indicates connectivity problems between your Docker client/daemon and container registries, DNS resolution failures, or resource constraints on the host system.

Typical symptoms

  • docker pull fails with 'Error response from daemon: Get https://registry-1.docker.io/v2/: context deadline exceeded'
  • Docker Compose fails to start services with timeout errors
  • Kubernetes pods stuck in ImagePullBackOff with context deadline exceeded
  • Docker Swarm nodes fail to join or communicate
  • docker build hangs and eventually times out when fetching base images
  • CI/CD pipelines fail intermittently with this error
  • Docker API operations become unresponsive
  • Containers fail to attach to overlay networks with deadline errors

Common causes

  1. Slow or unstable network connection to Docker registries
  2. DNS resolution failures or misconfiguration (especially with systemd-resolved)
  3. Firewall or proxy blocking connections to registry endpoints
  4. Docker daemon is unresponsive or under heavy load
  5. Large images exceeding default timeout during slow downloads
  6. Docker Swarm node in drain state preventing network resource allocation
  7. Corporate VPN or proxy interfering with Docker network traffic
  8. Registry server experiencing high latency or outages
  9. Mismatched Docker Engine versions in a Swarm cluster
  10. Required ports blocked for Docker Swarm communication

How to fix "context deadline exceeded"

1Verify network connectivity to Docker registry

First, check if you can reach the Docker registry from your host:

bash
# Test connectivity to Docker Hub
curl -I https://registry-1.docker.io/v2/

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

# Check for latency issues
ping -c 5 registry-1.docker.io

If these commands fail or show high latency, you have a network connectivity issue that needs to be resolved first.

2Configure DNS settings

DNS misconfiguration is one of the most common causes. On Linux systems using systemd-resolved, Docker may not be able to use the localhost DNS resolver:

bash
# Check current DNS configuration
cat /etc/resolv.conf

If you see nameserver 127.0.0.53, configure Docker to use public DNS:

bash
sudo nano /etc/docker/daemon.json

Add or update:

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

Then restart Docker:

bash
sudo systemctl restart docker
3Increase timeout for Docker Compose

If using Docker Compose, increase the HTTP timeout:

bash
# Set environment variable before running compose
export COMPOSE_HTTP_TIMEOUT=200

# Or inline with the command
COMPOSE_HTTP_TIMEOUT=200 docker-compose up

For persistent configuration, add to your shell profile (~/.bashrc or ~/.zshrc):

bash
export COMPOSE_HTTP_TIMEOUT=200
4Manually pull images before deployment

For Kubernetes or orchestration platforms with internal timeouts, pre-pull large images manually:

bash
# Pull the image directly (no orchestration timeout)
docker pull mcr.microsoft.com/mssql/server:2019-latest

# Verify it's cached locally
docker images | grep mssql

Once cached locally, subsequent deployments will use the local image instead of timing out during download.

5Check Docker Swarm node state

If using Docker Swarm, verify nodes are not in drain state:

bash
# Check node availability
docker node ls

# Inspect specific node status
docker node inspect --format '{{.Spec.Availability}}' <node-name>

If a node shows "drain", it cannot receive overlay network resources, causing deadline errors:

bash
# Activate the node
docker node update --availability active <node-name>
6Verify required ports are open

Docker Swarm requires specific ports for communication. Ensure these are open:

- TCP 2377: Cluster management communications
- TCP/UDP 7946: Node communication
- UDP 4789: Overlay network traffic

Check firewall rules:

bash
# For firewalld
sudo firewall-cmd --list-all

# For ufw
sudo ufw status

# Open required ports (firewalld example)
sudo firewall-cmd --permanent --add-port=2377/tcp
sudo firewall-cmd --permanent --add-port=7946/tcp
sudo firewall-cmd --permanent --add-port=7946/udp
sudo firewall-cmd --permanent --add-port=4789/udp
sudo firewall-cmd --reload
7Check Docker daemon health

Verify the Docker daemon is responsive:

bash
# Check Docker service status
sudo systemctl status docker

# Test daemon responsiveness
docker info

# View daemon logs for errors
sudo journalctl -u docker -n 50 --no-pager

If the daemon is unresponsive, restart it:

bash
sudo systemctl restart docker

For persistent issues, enable debug mode in /etc/docker/daemon.json:

json
{
  "debug": true
}
8Ensure consistent Docker Engine versions

In Swarm clusters, mismatched versions can cause timeout issues:

bash
# Check versions across all nodes
docker node ls --format '{{.Hostname}}: {{.EngineVersion}}'

# Or on each node individually
docker version --format '{{.Server.Version}}'

If versions differ significantly, upgrade nodes to a consistent version:

bash
# On Debian/Ubuntu
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

Advanced notes

GitLab Runner Configuration: If using GitLab CI with Kubernetes executor, increase the poll_timeout in your runner's config.toml file to handle slower cluster API responses.

Azure Container Registry: For ACR-specific deadline issues, verify your registry's sign-in server DNS resolves correctly with nslookup <registry-name>.azurecr.io. Private endpoints may require specific DNS configuration.

Proxy Environments: In corporate environments, ensure Docker is configured to use your proxy:

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

BuildKit Timeouts: For docker build timeouts with BuildKit, you may see "failed to solve: DeadlineExceeded". This often relates to slow base image pulls. Consider using a local registry mirror or pre-caching base images.

Rootless Docker: In rootless mode, networking uses slirp4netns which can have different timeout characteristics. Consider adjusting slirp4netns settings if experiencing consistent timeouts.

WSL2 Considerations: On Windows with WSL2, network issues can arise from DNS configuration conflicts between Windows and the WSL2 VM. Try adding your Windows host DNS to the WSL2 resolv.conf.

Frequently asked questions

What does "context deadline exceeded" mean?
The "context deadline exceeded" error is a timeout message originating from Go's context package, which Docker uses internally. When you see this error, it means that a Docker API request or network operation took longer than the configured timeout and was cancelled. This error commonly appears during operations like pulling images from a registry, pushing images, or when the Docker daemon fails to respond in time.
How do I fix "context deadline exceeded"?
The 'context deadline exceeded' error occurs when a Docker operation fails to complete within the allotted timeout period. This typically indicates network connectivity issues, DNS resolution failures, slow registry responses, or Docker daemon problems.
What causes "context deadline exceeded"?
Slow or unstable network connection to Docker registries DNS resolution failures or misconfiguration (especially with systemd-resolved) Firewall or proxy blocking connections to registry endpoints
Is the "context deadline exceeded" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading