Jump to solution
Verify

urllib3 Connection fails via https when certificate contains IPv6 address in SAN (Fix)

Fixed
Spec
Package
urllib3
Fixed In
1.25
Python
2.7
Verdict
Status
Fixed
Safe for prod
Yes
Risk
Low
Last verified
2026-02-09
Own content ratio
0.39
#1269 ai dns tls Updated: 2026-02-13
Issue #1269

The Fix

pip install urllib3==1.25

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

Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.

Jump to Verify Open PR/Commit
@@ -22,6 +22,14 @@ dev (master) ``urllib3[brotli]`` extra. (Pull #1532) +* Add TLSv1.3 support to CPython, pyOpenSSL, and SecureTransport ``SSLContext`` + implementations. (Pull #1496) +
repro.py
File "/usr/local/lib/python2.7/dist-packages/urllib3/connection.py", line 337, in connect cert = self.sock.getpeercert() File "/usr/local/lib/python2.7/dist-packages/urllib3/contrib/pyopenssl.py", line 348, in getpeercert 'subjectAltName': get_subj_alt_name(x509) File "/usr/local/lib/python2.7/dist-packages/urllib3/contrib/pyopenssl.py", line 222, in get_subj_alt_name for name in ext.get_values_for_type(x509.DNSName) File "/usr/local/lib/python2.7/dist-packages/urllib3/contrib/pyopenssl.py", line 175, in _dnsname_to_stdlib name = idna_encode(name) File "/usr/local/lib/python2.7/dist-packages/urllib3/contrib/pyopenssl.py", line 173, in idna_encode return idna.encode(name) File "/usr/local/lib/python2.7/dist-packages/idna/core.py", line 355, in encode result.append(alabel(label)) File "/usr/local/lib/python2.7/dist-packages/idna/core.py", line 265, in alabel raise IDNAError('The label {0} is not a valid A-label'.format(label)) IDNAError: The label 2001:db8::17 is not a valid A-label
verify
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.
fix.md
Option A — Upgrade to fixed release\npip install urllib3==1.25\nWhen NOT to use: This fix should not be applied if the application does not require IPv6 support.\n\n

Why This Fix Works in Production

  • Trigger: cert = self.sock.getpeercert()
  • Mechanism: The certificate validation fails due to improper handling of IPv6 addresses in the SubjectAlternativeName field
  • Why the fix works: Adds support for IPv6 addresses in the subjectAltName section of certificates, resolving the issue with certificate validation for IPv6 addresses. (first fixed release: 1.25).
Production impact:
  • If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.

Why This Breaks in Prod

  • Shows up under Python 2.7 in real deployments (not just unit tests).
  • The certificate validation fails due to improper handling of IPv6 addresses in the SubjectAlternativeName field
  • Surfaces as: File "/usr/local/lib/python2.7/dist-packages/urllib3/connection.py", line 337, in connect

Proof / Evidence

  • GitHub issue: #1269
  • Fix PR: https://github.com/urllib3/urllib3/pull/1496
  • First fixed release: 1.25
  • Reproduced locally: No (not executed)
  • Last verified: 2026-02-09
  • Confidence: 0.95
  • Did this fix it?: Yes (upstream fix exists)
  • Own content ratio: 0.39

Discussion

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

Jump to Sources Open on GitHub
“Can you please try installing the ipaddress module to see if that resolves your issue?”
@Lukasa · 2017-09-19 · confirmation · source
“That module is installed. Actually this seems to be an issue with the cryptography module that can be avoided by omitting the DNS:2001:db8::17 part and…”
@jharbott · 2017-09-20 · confirmation · source
“Reopening since even after fixing https://github.com/pyca/cryptography/issues/3943 I'm still seeing another traceback within urllib3 now:”
@jharbott · 2017-09-27 · source
“This looks like it's in the same vein as our idna issues in Requests”
@nateprewitt · 2017-09-27 · source

Failure Signature (Search String)

  • cert = self.sock.getpeercert()

Error Message

Stack trace
error.txt
Error Message ------------- File "/usr/local/lib/python2.7/dist-packages/urllib3/connection.py", line 337, in connect cert = self.sock.getpeercert() File "/usr/local/lib/python2.7/dist-packages/urllib3/contrib/pyopenssl.py", line 348, in getpeercert 'subjectAltName': get_subj_alt_name(x509) File "/usr/local/lib/python2.7/dist-packages/urllib3/contrib/pyopenssl.py", line 222, in get_subj_alt_name for name in ext.get_values_for_type(x509.DNSName) File "/usr/local/lib/python2.7/dist-packages/urllib3/contrib/pyopenssl.py", line 175, in _dnsname_to_stdlib name = idna_encode(name) File "/usr/local/lib/python2.7/dist-packages/urllib3/contrib/pyopenssl.py", line 173, in idna_encode return idna.encode(name) File "/usr/local/lib/python2.7/dist-packages/idna/core.py", line 355, in encode result.append(alabel(label)) File "/usr/local/lib/python2.7/dist-packages/idna/core.py", line 265, in alabel raise IDNAError('The label {0} is not a valid A-label'.format(label)) IDNAError: The label 2001:db8::17 is not a valid A-label

Minimal Reproduction

repro.py
File "/usr/local/lib/python2.7/dist-packages/urllib3/connection.py", line 337, in connect cert = self.sock.getpeercert() File "/usr/local/lib/python2.7/dist-packages/urllib3/contrib/pyopenssl.py", line 348, in getpeercert 'subjectAltName': get_subj_alt_name(x509) File "/usr/local/lib/python2.7/dist-packages/urllib3/contrib/pyopenssl.py", line 222, in get_subj_alt_name for name in ext.get_values_for_type(x509.DNSName) File "/usr/local/lib/python2.7/dist-packages/urllib3/contrib/pyopenssl.py", line 175, in _dnsname_to_stdlib name = idna_encode(name) File "/usr/local/lib/python2.7/dist-packages/urllib3/contrib/pyopenssl.py", line 173, in idna_encode return idna.encode(name) File "/usr/local/lib/python2.7/dist-packages/idna/core.py", line 355, in encode result.append(alabel(label)) File "/usr/local/lib/python2.7/dist-packages/idna/core.py", line 265, in alabel raise IDNAError('The label {0} is not a valid A-label'.format(label)) IDNAError: The label 2001:db8::17 is not a valid A-label

Environment

  • Python: 2.7

What Broke

Users experience connection failures when accessing URLs with IPv6 addresses in SANs.

Why It Broke

The certificate validation fails due to improper handling of IPv6 addresses in the SubjectAlternativeName field

Fix Options (Details)

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

pip install urllib3==1.25

When NOT to use: This fix should not be applied if the application does not require IPv6 support.

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/1496

First fixed release: 1.25

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

Get updates

We publish verified fixes weekly. No spam.

Subscribe

When NOT to Use This Fix

  • This fix should not be applied if the application does not require IPv6 support.

Verify Fix

verify
Re-run the minimal reproduction on your broken version, then apply the fix and re-run.

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

VersionStatus
1.25 Fixed

Related Issues

No related fixes found.

Cluster: urllib3:configuration-error urllib3 hub urllib3 best practices All hubs All clusters
Related clusters: Data consistency SSL handshake Other

Sources

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

Source & Disclaimer: Analysis derived from GitHub Issue #1269. Not affiliated with the library maintainers. Verify before production use.