Self-Healing CI: Auto-Retrying a pip Index SSL Error
A pip install that fails with an SSL error against the index usually hit a momentary TLS or proxy hiccup, not a certificate or package problem -- the same install succeeds on a retry.
The problem
A pip install fails with an SSL error while contacting the package index -- a handshake failure or a reset during the TLS exchange. The package exists and the index is up; a momentary TLS or proxy hiccup interrupted the connection. A human re-runs the job and the install completes unchanged.
Could not fetch URL https://pypi.org/simple/requests/: There was a problem
confirming the ssl certificate: HTTPSConnectionPool(... Read timed out)Why it happens
Every index request rides a TLS handshake, and a brief network interruption, a momentary proxy hiccup, or transient congestion during that exchange can surface as an SSL error even though the certificate chain and the package are perfectly valid.
It is transport flakiness, not a certificate or package problem: the index is reachable and the same install succeeds once the connection is retried.
The manual fix
Manual mitigations for a pip index SSL blip:
- Re-run the job to retry the install.
- Use pip’s built-in retry and a higher timeout (
--retries,--timeout). - Point at a reliable internal index mirror to reduce dependence on the public index.
pip install --retries 5 --timeout 60 -r requirements.txtHow this gets automated
A transient index SSL error has a recognizable handshake-blip signature, and the safe response is to retry the request. A self-healing CI pipeline detects the SSL/transport failure, retries the install with backoff, and only escalates if the error persists across retries, which is the real signal of a genuine certificate or index problem rather than a momentary hiccup.