Self-Healing CI: Recovering from TLS Handshake Timeouts
A TLS handshake that times out is a stalled connection setup, not a broken certificate - the same secure connection establishes fine on a clean retry.
The problem
A step that opens an HTTPS connection fails with TLS handshake timeout (or similar) before any data transfers. The certificate chain is valid and the endpoint is up; a human re-runs the job and the handshake completes unchanged.
net/http: TLS handshake timeout
# or
OpenSSL SSL_connect: Connection reset by peer ... during TLS handshakeWhy it happens
The TLS handshake is a multi-round-trip negotiation at connection setup. Under congestion or a brief upstream slowdown, those round trips exceed the client’s handshake deadline and the connection is abandoned before the certificate is even validated.
Because the failure happens before any payload moves, it reflects transient network conditions rather than anything about the request, the endpoint, or your code.
The manual fix
Manual mitigations for handshake timeouts:
- Re-run the job so the connection can be re-established.
- Add retry-with-backoff around the connecting command so one stalled handshake does not fail the step.
- Raise client handshake/connect timeouts and reduce concurrent new connections that contend for the network at startup.
How this gets automated
A handshake timeout is transient by definition - it occurs before any meaningful work - so the safe response is to retry the connection. A self-healing CI pipeline detects the handshake-timeout signature, retries with backoff, and only surfaces a persistent failure, which is the real signal of an endpoint or certificate problem rather than congestion.