docker network_error ai_generated partial

Error response from daemon: Get https://registry-1.docker.io/v2/: net/http: TLS handshake timeout

ID: docker/tls-handshake-timeout

Also available as: JSON · Markdown · 中文
75%Fix Rate
88%Confidence
1Evidence
2023-09-05First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
Docker 20.10.0 active — — —
Docker 24.0.0 active — — —
Docker 25.0.0 active — — —
Docker CE 26.0.0 active — — —

Root Cause

The Docker daemon cannot establish a TLS connection to the Docker Hub registry due to network latency, firewall blocks, or DNS resolution issues.

generic

中文

Docker 守护进程无法与 Docker Hub 注册表建立 TLS 连接，原因是网络延迟、防火墙阻止或 DNS 解析问题。

Official Documentation

https://docs.docker.com/engine/reference/commandline/pull/

Workarounds

  1. 80% success Configure Docker daemon to use a mirror registry by editing /etc/docker/daemon.json: add '{"registry-mirrors": ["https://mirror.gcr.io"]}' and restart Docker. Then pull the image again. 
    Configure Docker daemon to use a mirror registry by editing /etc/docker/daemon.json: add '{"registry-mirrors": ["https://mirror.gcr.io"]}' and restart Docker. Then pull the image again.
  2. 60% success Increase TLS handshake timeout by setting environment variable: 'export DOCKER_CLIENT_TIMEOUT=120' and 'export COMPOSE_HTTP_TIMEOUT=120' before running docker commands. 
    Increase TLS handshake timeout by setting environment variable: 'export DOCKER_CLIENT_TIMEOUT=120' and 'export COMPOSE_HTTP_TIMEOUT=120' before running docker commands.
  3. 70% success Check and update DNS settings: add '8.8.8.8' to /etc/resolv.conf or use systemd-resolved: 'sudo resolvectl dns docker0 8.8.8.8'. 
    Check and update DNS settings: add '8.8.8.8' to /etc/resolv.conf or use systemd-resolved: 'sudo resolvectl dns docker0 8.8.8.8'.

中文步骤

  1. Configure Docker daemon to use a mirror registry by editing /etc/docker/daemon.json: add '{"registry-mirrors": ["https://mirror.gcr.io"]}' and restart Docker. Then pull the image again.
  2. Increase TLS handshake timeout by setting environment variable: 'export DOCKER_CLIENT_TIMEOUT=120' and 'export COMPOSE_HTTP_TIMEOUT=120' before running docker commands.
  3. Check and update DNS settings: add '8.8.8.8' to /etc/resolv.conf or use systemd-resolved: 'sudo resolvectl dns docker0 8.8.8.8'.

Dead Ends

Common approaches that don't work:

  1. 60% fail

    Setting HTTP_PROXY without HTTPS_PROXY in daemon.json does not affect TLS connections; the timeout persists.

  2. 70% fail

    Flushing DNS cache (e.g., 'sudo systemctl restart systemd-resolved') rarely resolves the issue if the root cause is network congestion or firewall rules.