urllib3 TLS-in-TLS not working with IP proxies (Fix)

The Fix

pip install urllib3==1.26.5

Based on closed urllib3/urllib3 issue #2400 · 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

@@ -56,6 +56,7 @@ class BrokenPipeError(Exception):
     assert_fingerprint,
     create_urllib3_context,
+    is_ipaddress,
     resolve_cert_reqs,
     resolve_ssl_version,

repro.py

def get(url, proxy, username, password):

    headers  = urllib3.make_headers(proxy_basic_auth=f'{username}:{password}')
    proxy    = urllib3.ProxyManager('https://{}'.format(proxy), proxy_headers=headers)
    response = proxy.request("GET", url)            # Exception trigger here

    return (response)

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.26.5\nWhen NOT to use: This fix is not applicable if using non-TLS proxies or if the proxy does not support hostname verification.\n\nOption C — Workaround\nwould be to use an hostname if you have one or just stop using TLS-in-TLS. (This has nothing to do with basic authentication.)\nWhen NOT to use: This fix is not applicable if using non-TLS proxies or if the proxy does not support hostname verification.\n\n

Why This Fix Works in Production

Trigger: ValueError: check_hostname requires server_hostname
Mechanism: The error occurs due to SNI being sent when connecting to an IP address proxy
Why the fix works: Fixes issue #2400 by relying on urllib3's hostname matching for HTTPS proxy validation, addressing a bug with IP addresses and SNI. (first fixed release: 1.26.5).

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 3.9.6 in real deployments (not just unit tests).
The error occurs due to SNI being sent when connecting to an IP address proxy
Surfaces as: ValueError: check_hostname requires server_hostname

Proof / Evidence

GitHub issue: #2400
Fix PR: https://github.com/urllib3/urllib3/pull/2419
First fixed release: 1.26.5
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.31

Discussion

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

Jump to Sources Open on GitHub

“@Kcam9908 Did you read my reply to you directly above? In summary we don't think the issue you're seeing will be resolved by the PR…”

@sethmlarson · 2021-09-10 · confirmation · source

“The PR for relying on urllib3's hostname matching logic for verifying proxy certificates is merged. However there's still a bug with IPv6 addresses we'd like…”

@sethmlarson · 2021-09-16 · confirmation · source

“Hi there, I'm currently working on a project that relies on a vulnerability fixed in v1.26.5, but this issue keeps me from using our proxies…”

@Kcam9908 · 2021-09-07 · confirmation · source

“I noticed there was a PR opened. Do you guys have a timeline for when the fix for this issue will be released? My team…”

@Kcam9908 · 2021-09-10 · confirmation · source

Failure Signature (Search String)

ValueError: check_hostname requires server_hostname

Error Message

Stack trace

error.txt

Error Message
-------------
ValueError: check_hostname requires server_hostname

Stack trace

error.txt

Error Message
-------------
Traceback (most recent call last):
[...]
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/request.py", line 74, in request
    return self.request_encode_url(
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/request.py", line 96, in request_encode_url
    return self.urlopen(method, url, **extra_kw)
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/poolmanager.py", line 532, in urlopen
    return super(ProxyManager, self).urlopen(method, url, redirect=redirect, **kw)
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/poolmanager.py", line 375, in urlopen
    response = conn.urlopen(method, u.request_uri, **kw)
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/connectionpool.py", line 696, in urlopen
    self._prepare_proxy(conn)
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/connectionpool.py", line 964, in _prepare_proxy
    conn.connect()
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/connection.py", line 359, in connect
    conn = self._connect_tls_proxy(hostname, conn)
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/connection.py", lin
... (truncated) ...

Stack trace

error.txt

Error Message
-------------
Traceback (most recent call last):
  File "/home/janemba/projects/test/examples/urllibway.py", line 51, in <module>
    main(opt.url)
  File "/home/janemba/projects/test/examples/urllibway.py", line 31, in main
    response = get(url, proxy, login, password)
  File "/home/janemba/projects/test/examples/urllibway.py", line 15, in get
    response = proxy.request("GET", url)
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/request.py", line 74, in request
    return self.request_encode_url(
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/request.py", line 96, in request_encode_url
    return self.urlopen(method, url, **extra_kw)
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/poolmanager.py", line 532, in urlopen
    return super(ProxyManager, self).urlopen(method, url, redirect=redirect, **kw)
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/poolmanager.py", line 375, in urlopen
    response = conn.urlopen(method, u.request_uri, **kw)
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/connectionpool.py", line 696, in urlopen
    self._prepare_proxy(conn)
  File "/home/janemba/.virtualenv/test-rCp672mu-py3.9/lib64/python3.9/site-packages/urllib3/connectionpool.py", lin
... (truncated) ...

Minimal Reproduction

repro.py

def get(url, proxy, username, password):

    headers  = urllib3.make_headers(proxy_basic_auth=f'{username}:{password}')
    proxy    = urllib3.ProxyManager('https://{}'.format(proxy), proxy_headers=headers)
    response = proxy.request("GET", url)            # Exception trigger here

    return (response)

Environment

Python: 3.9.6
urllib3: 1.25.11

What Broke

Users experience exceptions when attempting to connect to HTTPS websites through IP proxies.

Why It Broke

The error occurs due to SNI being sent when connecting to an IP address proxy

Fix Options (Details)

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

pip install urllib3==1.26.5

When NOT to use: This fix is not applicable if using non-TLS proxies or if the proxy does not support hostname verification.

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

Option C — Workaround Temporary workaround

would be to use an hostname if you have one or just stop using TLS-in-TLS. (This has nothing to do with basic authentication.)

When NOT to use: This fix is not applicable if using non-TLS proxies or if the proxy does not support hostname verification.

Use only if you cannot change versions today. Treat this as a stopgap and remove once upgraded.

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

First fixed release: 1.26.5

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

When NOT to Use This Fix

This fix is not applicable if using non-TLS proxies or if the proxy does not support hostname verification.

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

Version	Status
1.26.5	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.

urllib3 TLS-in-TLS not working with IP proxies (Fix)

The Fix

Why This Fix Works in Production

Why This Breaks in Prod

Proof / Evidence

Discussion

Failure Signature (Search String)

Error Message

Minimal Reproduction

Environment

What Broke

Why It Broke

Fix Options (Details)

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

Option C — Workaround Temporary workaround

Get updates

When NOT to Use This Fix

Verify Fix

Did This Fix Work in Your Case?

Prevention

Version Compatibility Table

Related Issues

Sources