Docker TLS Handshake Time Out Error Solution

When using Docker, you may occasionally encounter the TLS handshake time out error. This happens when the Docker client fails to establish a secure connection with the registry within the expected time. Slow internet connections or overloaded registry servers are common causes.

In this guide, we will explain the Docker TLS handshake time out error solution step by step.

What Is TLS Handshake Time Out?

TLS handshake is the process of establishing a secure connection between a client and a server.
If the process cannot be completed in the given time frame, you will see the Docker TLS handshake time out error.

The main reasons include:

• Slow or unstable internet connection

• Overloaded Docker registry servers

• IPv6 connection issues

• Misconfigured Docker daemon settings

How to Fix Docker TLS Handshake Time Out Error

You can resolve the error by optimizing the Docker daemon configuration. Follow these steps:

1. Open Docker Daemon Configuration

Open the configuration file with:

sudo nano /etc/docker/daemon.json

2. Add Mirror and Disable IPv6

Insert or update the file with the following content:

{
  "ipv6": false,
  "registry-mirrors": ["https://mirror.gcr.io"]
}

Explanation:

• Disabling IPv6 prevents delays caused by slow IPv6 connections.

• Adding a registry mirror speeds up image pulling.

3. Restart Docker Service

Save the file and restart Docker:

sudo systemctl restart docker

Additional Tips

• If the issue persists, add multiple registry mirrors.

• Check your DNS settings and try fast DNS servers like Google DNS (8.8.8.8).

• Pull images during off-peak hours for a faster response.