Troubleshooting Docker Timeout Errors on Debian 11

Docker timeout errors on Debian 11 frequently indicate underlying DNS resolution problems affecting containers’ ability to reach external network resources. This often occurs when the host’s systemd-resolved or specific network configurations conflict with Docker’s internal DNS mechanisms.

1. The Root Cause

On Debian 11, Docker container timeout errors typically stem from DNS resolution failures. This usually happens when the host’s systemd-resolved configuration or custom network setups interfere with the DNS servers Docker assigns to its containers, preventing them from resolving external domain names.

2. Quick Fix (CLI)

To quickly address DNS-related timeouts, configure the Docker daemon to use reliable public DNS servers.

# Create or edit the Docker daemon configuration file
sudo nano /etc/docker/daemon.json

Add the following content to the daemon.json file. If the file already exists, ensure the dns array is correctly integrated or updated.

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

Save and exit (Ctrl+X, Y, Enter). Then restart the Docker service:

sudo systemctl restart docker

3. Configuration Check

Verify and ensure the Docker daemon’s configuration explicitly defines trusted DNS servers for all containers.

Edit the configuration file located at /etc/docker/daemon.json.

sudo nano /etc/docker/daemon.json

Confirm or modify the file to include a dns key with an array of public DNS server IP addresses. Consider adding Cloudflare’s DNS as an alternative or additional entry for redundancy.

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

This configuration instructs the Docker daemon to use Google’s (8.8.8.8, 8.8.4.4) and Cloudflare’s (1.1.1.1) DNS servers for all containers it manages, bypassing potential host-level DNS issues. After any changes, always restart the Docker service using sudo systemctl restart docker.

4. Verification

To confirm the Docker daemon is now using the specified DNS servers and that containers can resolve external domains, execute the following commands:

Check the Docker daemon’s configured DNS servers:

sudo docker info | grep "DNS Server"

You should see output similar to: DNS Server: 8.8.8.8 and DNS Server: 8.8.4.4.

Next, run a test container to confirm external DNS resolution works correctly:

sudo docker run --rm busybox nslookup google.com

A successful output will display google.com resolving to its IP addresses, indicating the timeout error related to DNS has been resolved.