DNS / IPv6 Timeout — "TLS handshake timeout"
Symptom
Helm or Docker registry operations hang with
TLS handshake timeout.
Root Cause
IPv6 is enabled on the server but the outbound IPv6 route is broken or unreachable. The system's DNS resolver returns an IPv6 AAAA record for the registry, the client attempts an IPv6 connection, the TCP handshake times out, and only then does it fall back to IPv4 — causing long delays or total failure if IPv4 fallback is also misconfigured.
Fix
1. Configure /etc/gai.conf to prefer IPv4
Edit /etc/gai.conf and uncomment or add:
precedence ::ffff:0:0/96 100
This gives IPv4-mapped IPv6 addresses higher precedence than native IPv6.
2. Configure systemd-resolved to use a reliable DNS server
Edit /etc/systemd/resolved.conf:
[Resolve]
DNS=8.8.8.8
FallbackDNS=1.1.1.1
3. Restart systemd-resolved
sudo systemctl restart systemd-resolved
Verification
# Confirm DNS is now using the configured server
resolvectl status
# Test registry connectivity without IPv6 hang
curl -v https://registry-1.docker.io/v2/ 2>&1 | grep -i "connected\|IPv6\|TLS"
You should see a quick TCP connection to an IPv4 address and a successful TLS handshake.