urllib3 Add additional documentation for HTTPSConnection

The Fix

pip install urllib3==1.25.11

Based on closed urllib3/urllib3 issue #1884 · PR/commit linked

Production note: This usually shows up under retries/timeouts. Treat it as a side-effect risk until you can verify behavior with a canary + real traffic.

Open PR/Commit

@@ -172,6 +172,45 @@ verified with that bundle will succeed. It's recommended to use a separate
 the custom certificate.
 
+.. _sni_custom:
+
+Custom SNI Hostname

fix.md

Option A — Upgrade to fixed release\npip install urllib3==1.25.11\nWhen NOT to use: This fix is not applicable if the documentation is already sufficient for user needs.\n\n

Why This Fix Works in Production

Trigger: I did eventually find it (I assume with the same meaning) documented on [this utility
Mechanism: Documentation for HTTPSConnection parameters was insufficient and unclear for users
Why the fix works: Documents parameters for HTTPSConnection and adds advanced usage documentation for SNI connections to an IP. (first fixed release: 1.25.11).

Why This Breaks in Prod

Documentation for HTTPSConnection parameters was insufficient and unclear for users
Production symptom (often without a traceback): I did eventually find it (I assume with the same meaning) documented on [this utility function](https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html#urllib3.util.ssl_wrap_socket).

Proof / Evidence

GitHub issue: #1884
Fix PR: https://github.com/urllib3/urllib3/pull/1912
First fixed release: 1.25.11
Reproduced locally: No (not executed)
Last verified: 2026-02-09
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.75

Discussion

High-signal excerpts from the issue thread (symptoms, repros, edge-cases).

Jump to Sources Open on GitHub

“I think that course of action would be perfect! If I can find time (and remember to do it) I'll work up a PR to…”

@sirosen · 2020-06-04 · source

“HTTPSConnection is a thin wrapper over util.ssl_wrap_socket, which creates a SSLContext, loads certificates, and wraps the socket”

@pquentin · 2020-06-02 · source

Failure Signature (Search String)

I did eventually find it (I assume with the same meaning) documented on [this utility
1. Mention in `HTTPSConnection` that the parameters are documented in `util.ssl_wrap_socket`

Copy-friendly signature

signature.txt

Failure Signature
-----------------
I did eventually find it (I assume with the same meaning) documented on [this utility function](https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html#urllib3.util.ssl_wrap_socket).
1. Mention in `HTTPSConnection` that the parameters are documented in `util.ssl_wrap_socket`

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
I did eventually find it (I assume with the same meaning) documented on [this utility function](https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html#urllib3.util.ssl_wrap_socket).
1. Mention in `HTTPSConnection` that the parameters are documented in `util.ssl_wrap_socket`

What Broke

Users faced confusion and potential misuse due to lack of documentation on parameters.

Why It Broke

Documentation for HTTPSConnection parameters was insufficient and unclear for users

Fix Options (Details)

Option A — Upgrade to fixed release Safe default (recommended)

pip install urllib3==1.25.11

When NOT to use: This fix is not applicable if the documentation is already sufficient for user needs.

Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.

Fix reference: https://github.com/urllib3/urllib3/pull/1912

First fixed release: 1.25.11

Last verified: 2026-02-09. Validate in your environment.

When NOT to Use This Fix

This fix is not applicable if the documentation is already sufficient for user needs.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Add a CI check that diffs key outputs after upgrades (OpenAPI schema snapshots, JSON payload shapes, CLI output).
Upgrade behind a canary and run integration tests against the canary before 100% rollout.
Add a TLS smoke test that performs a real handshake in CI (include CA bundle validation and hostname checks).
Alert on handshake failures by error string and endpoint to catch cert/CA changes quickly.

Version Compatibility Table

Version	Status
1.25.11	Fixed

Related Issues

No related fixes found.

Cluster: urllib3:ssl-handshake urllib3 hub urllib3 best practices All hubs All clusters

Related clusters: Configuration error Data consistency Other

Sources

We don’t republish the full GitHub discussion text. Use the links above for context.

urllib3 Add additional documentation for HTTPSConnection parameters (Fix)