The Fix
pip install urllib3==1.26.10
Based on closed urllib3/urllib3 issue #2564 · 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%.
@@ -60,6 +60,7 @@ class BaseSSLError(BaseException): # type: ignore[no-redef]
)
from .util.ssl_match_hostname import CertificateError, match_hostname
+from .util.url import Url
# Not a no-op, we're adding this to the namespace so it can be imported.
repro.py
def test_http_proxymanager_connected_to_https_proxy(
self
) -> None:
errored = Event()
def http_socket_handler(listener: socket.socket) -> None:
sock = listener.accept()[0]
sock.send(b"HTTP/1.0 501 Not Implemented\r\nConnection: close\r\n\r\n")
errored.wait()
sock.close()
self._start_server(http_socket_handler)
base_url = f"http://{self.host}:{self.port}"
with ProxyManager(base_url) as proxy:
with pytest.raises(MaxRetryError) as e:
proxy.request("GET", f"https://example.com", retries=0)
errored.set() # Avoid a ConnectionAbortedError on Windows.
assert type(e.value.reason) == ProxyError
assert "Your proxy appears to only use HTTP and not HTTPS" in str(
e.value.reason
)
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.10\nWhen NOT to use: This fix is not applicable for genuine HTTPS proxy configurations.\n\n
Why This Fix Works in Production
- Trigger: Incorrect "Your proxy appears to only use HTTP and not HTTPS" error message during connection errors to HTTPS websites using a HTTP proxy
- Mechanism: The error message incorrectly assumes all 'wrong version number' errors are due to HTTP proxies
- Why the fix works: Fixes an incorrect error message that appears during connection errors to HTTPS websites when using a HTTP proxy. (first fixed release: 1.26.10).
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.10.1 in real deployments (not just unit tests).
- The error message incorrectly assumes all 'wrong version number' errors are due to HTTP proxies
- Production symptom (often without a traceback): Incorrect "Your proxy appears to only use HTTP and not HTTPS" error message during connection errors to HTTPS websites using a HTTP proxy
Proof / Evidence
- GitHub issue: #2564
- Fix PR: https://github.com/urllib3/urllib3/pull/2613
- First fixed release: 1.26.10
- 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.54
Verified Execution
We executed the runnable minimal repro in a temporary environment and captured exit codes + logs.
- Status: PASS
- Ran: 2026-02-11T16:52:29Z
- Package: urllib3
- Fixed: 1.26.10
- Mode: fixed_only
- Outcome: ok
Logs
affected (exit=None)
fixed (exit=0)
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“Thanks for reporting this, I agree that we should only be giving this error message on HTTPS proxies. I agree with your solution, would you…”
“Hey @sethmlarson, I can work on this”
“@hramezani I'm not sure the new test function is correct to reproduce this error”
“@sethmlarson I am going to prepare a test for this change based on test_https_proxymanager_connected_to_http_proxy https://github.com/urllib3/urllib3/blob/f0dffb4e2437cb2da2ba0a6bbea6211f6fd0fa4b/test/with_dummyserver/test_socketlevel.py#L1163 Here is the new”
Failure Signature (Search String)
- Incorrect "Your proxy appears to only use HTTP and not HTTPS" error message during connection errors to HTTPS websites using a HTTP proxy
- 2. Wait for an error in the proxy to trigger a "wrong version number" error.
Copy-friendly signature
signature.txt
Failure Signature
-----------------
Incorrect "Your proxy appears to only use HTTP and not HTTPS" error message during connection errors to HTTPS websites using a HTTP proxy
2. Wait for an error in the proxy to trigger a "wrong version number" error.
Error Message
Signature-only (no traceback captured)
error.txt
Error Message
-------------
Incorrect "Your proxy appears to only use HTTP and not HTTPS" error message during connection errors to HTTPS websites using a HTTP proxy
2. Wait for an error in the proxy to trigger a "wrong version number" error.
Minimal Reproduction
repro.py
def test_http_proxymanager_connected_to_https_proxy(
self
) -> None:
errored = Event()
def http_socket_handler(listener: socket.socket) -> None:
sock = listener.accept()[0]
sock.send(b"HTTP/1.0 501 Not Implemented\r\nConnection: close\r\n\r\n")
errored.wait()
sock.close()
self._start_server(http_socket_handler)
base_url = f"http://{self.host}:{self.port}"
with ProxyManager(base_url) as proxy:
with pytest.raises(MaxRetryError) as e:
proxy.request("GET", f"https://example.com", retries=0)
errored.set() # Avoid a ConnectionAbortedError on Windows.
assert type(e.value.reason) == ProxyError
assert "Your proxy appears to only use HTTP and not HTTPS" in str(
e.value.reason
)
Environment
- Python: 3.10.1
- urllib3: 1.26.8
What Broke
Users receive misleading error messages when connecting to HTTPS websites via HTTP proxies.
Why It Broke
The error message incorrectly assumes all 'wrong version number' errors are due to HTTP proxies
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
pip install urllib3==1.26.10
When NOT to use: This fix is not applicable for genuine HTTPS proxy configurations.
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Option D — Guard side-effects with OnceOnly Guardrail for side-effects
Mitigate duplicate external side-effects under retries/timeouts/agent loops by gating the operation before calling external systems.
- Place OnceOnly between your code/agent and real side-effects (Stripe, emails, CRM, APIs).
- Use a stable key per side-effect (e.g., customer_id + action + idempotency_key).
- Fail-safe: configure fail-open vs fail-closed based on blast radius and spend risk.
Show example snippet (optional)
onceonly.py
from onceonly import OnceOnly
import os
once = OnceOnly(api_key=os.environ["ONCEONLY_API_KEY"], fail_open=True)
# Stable idempotency key per real side-effect.
# Use a request id / job id / webhook delivery id / Stripe event id, etc.
event_id = "evt_..." # replace
key = f"stripe:webhook:{event_id}"
res = once.check_lock(key=key, ttl=3600)
if res.duplicate:
return {"status": "already_processed"}
# Safe to execute the side-effect exactly once.
handle_event(event_id)
When NOT to use: Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.
Fix reference: https://github.com/urllib3/urllib3/pull/2613
First fixed release: 1.26.10
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix is not applicable for genuine HTTPS proxy configurations.
- Do not use this to hide logic bugs or data corruption. Use it to block duplicate external side-effects and enforce tool permissions/spend caps.
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.10 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.