The docker pull is one of the basic commands in Docker, and it is used to fetch image files from Docker registries, adding them to your Docker host. When you run docker pull <image>, Docker checks the Docker Hub to make sure that the <image> that you are trying to pull is available, and if that is the case, it downloads the image layers.
Sometimes when you try to pull an image from the Docker registry, you could encounter some issues, and one of those issues is the TLS handshake timeout error which we will be uncovering today and learning how to resolve. This error is a very common one, as it usually shows that the client couldn’t connect securely with the Docker registry within a certain time frame. The error does not occur all the time, meaning that it could be influenced by different factors, which you will uncover in this guide.
Understanding The Error
The TLS handshake timeout error is a networking error that happens when your machine tries to create a connection with the server hosting the Docker images using the Transport Layer Security (TLS) protocol.
The TLS protocol is supposed to encrypt the data sent between your machine and the Docker registry. The initial part of the protocol that exchanges information between the client and server to establish a secure connection is the “handshake” in the error message.
The “timeout” occurs if the handshakes take longer than the defined time limit of the system. This could be due to a lot of reasons, such as network latency and firewall restrictions, and in rare cases, the issue could be with the Docker registry.
Troubleshooting
Step 1: Check Network Connection
The first step to take is to check your network connectivity when trying to troubleshoot the TLS handshake timeout error. You can use the ping command to test the Docker registry.
ping registry-1.docker.io
When you run this command, a small packet of information is sent to the Docker registry. If the connectivity is okay, you should see the following:
But if the ping test fails, meaning that the latency is high, you may need to improve your network connectivity.
Step 2: Verifying Docker Daemon Configuration
You can also check the configuration of your Docker daemon for any errors or misconfigurations.
Check the content of the Docker daemon configuration file and view the contents:
cat /etc/docker/daemon.json
This will display the contents of the daemon.json on your terminal.
Next, carefully review the output and see if there are any errors or not. Pay close attention to the proxy settings under the proxies key and TLS settings.
Then, correct any issues and edit the daemon.json file.
After making the changes, restart the Docker daemon for the changes to take effect.
sudo systemctl restart docker
Note that modifying system files can have significant effects on your system. Always make sure to back up any files before you modify them, and only make changes that you understand.
Step 3: Investigating Docker Registry Status
If your network connectivity is fine and your Docker daemon is correctly configured, the issue might be with the Docker registry. Check the status of the Docker registry you’re trying to pull from. If the registry is down or experiencing issues, you may need to wait until it’s back up, or you can try pulling from a different registry.
Conclusion
In this quick guide, you have learnt about the “Docker Pull Intermittent TLS Handshake Timeout” error and how to troubleshoot it. To prevent this error, it is essential to have a stable network connection, properly configure your network configuration, update regularly, and ensure that the Docker daemon has sufficient resources to operate efficiently. To learn more, you can visit the Docker official documentation.
