The Root Cause

Debian 11 (Bullseye) utilizes systemd-resolved for local DNS management, which can sometimes interfere with Docker’s internal DNS resolution mechanism. This conflict prevents the Docker daemon from correctly resolving hostnames for external image registries like Docker Hub, leading to HTTP 404 errors when attempting to pull images.

Quick Fix (CLI)

Explicitly configure DNS servers for the Docker daemon by creating or editing /etc/docker/daemon.json and restarting the Docker service.

sudo mkdir -p /etc/docker
sudo nano /etc/docker/daemon.json

Add the following content to the daemon.json file:

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

Save the file (Ctrl+O, Enter, Ctrl+X in nano). Then, restart the Docker daemon:

sudo systemctl restart docker

Configuration Check

The configuration file to verify or edit is /etc/docker/daemon.json. Ensure it contains a dns array with valid, accessible DNS server IP addresses.

Example lines to change/add:

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

Note: 8.8.8.8 and 8.8.4.4 are Google’s public DNS servers. You may substitute these with other reliable public DNS servers such as Cloudflare’s (1.1.1.1, 1.0.0.1) or your organization’s internal DNS servers if applicable.

Verification

To confirm the fix, attempt to pull a small, common Docker image from Docker Hub.

docker pull hello-world

A successful pull (e.g., Using default tag: latest, Status: Downloaded newer image for hello-world:latest) indicates the DNS resolution issue has been resolved.