How to resolve the Docker “Timeout exceeded while awaiting headers” error

Jack Wallen found Docker commands failing to pull down images on various machines. The issue perplexed him, but the solution turned out to be very simple.

Recently, I’ve noticed several instances where I go to either pull down a Docker image or run the docker compose up -d command, only to see the following error:

request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

I tried everything, from rebooting, logging in to Docker Hub and reinstalling Docker CE, but nothing worked to get around the error. It took me considerable troubleshooting, but I finally discovered the issue and I was shocked at the simplicity of the solution.

SEE: Hiring kit: Back-end Developer (TechRepublic Premium)

Most often, this issue is caused by the machine running the Docker command being behind a proxy. When that’s the case, the Docker command cannot successfully communicate to hub.docker.com. However, that was not the case with my instance. In fact, none of my servers are behind a proxy. So what gives?

How to resolve the Docker header timeout issue

The first thing you should try is to log in with the Docker command. To do that, you’ll need to first create an access token from within your DockerHub account:

1. Log in to your DockerHub account.
2. Click your profile image in the upper right corner.
3. Click Account Settings.
4. Go to the Security section.
5. Click New Access Token.
6. Give the new token a name and assign the Access Permissions.
7. Click Generate.
8. Copy the resultant access code to your clipboard.

Go to your terminal window on the machine running Docker and log in with the command:

docker login

You’ll be prompted for your DockerHub username followed by the access token. Paste the access token into the terminal and hit Enter on your keyboard. You should then be logged into DockerHub and are ready to go. Try and pull down an image such as with the command:

docker pull nginx

If that works, you’re good to go. If not, there’s one more thing you can try that will probably resolve the issue, as this is what did it for me.

It’s all about your DNS servers. I generally use the Cloudflare DNS servers of 1.0.0.1 and 1.1.1.1. With those DNS servers configured, the Docker pull commands have been failing me of late. To fix that issue, I simply switched to the Google DNS server of 8.8.8.8 and 8.8.4.4. Here’s how I made that change on Ubuntu Server 22.04.

Open your network device configuration file, such as with the command:

sudo nano /etc/netplan/00-installer-config.yml

In that file, make sure the nameservers entry looks like this:

nameservers:
addresses: [8.8.8.8,8.8.4.4]

Save and close the file. Apply the changes with:

sudo netplan apply

Once netplan has done its thing, attempt to pull down an image from DockerHub and you should see success.

It’s an incredibly simple solution to a problem that had vexed me for a while. Hopefully, this easy fix has Docker running as expected for you.

Subscribe to TechRepublic’s How To Make Tech Work on YouTube for all the latest tech advice for business pros from Jack Wallen.