Jump to solution
Verify

httpx Should we support bare hostnames in `ALL_PROXY`,`HTTP_PROXY`, `HTTPS_PROXY`? (Fix)

Fixed
Spec
Package
httpx
Fixed In
0.14.0
Python
3.8.4
Verdict
Status
Fixed
Safe for prod
No
Risk
Medium
Last verified
2026-02-09
Own content ratio
0.23
#1082 ai llm memory-leak timeouts tls Updated: 2026-02-13
Issue #1082

The Fix

Upgrade to version 0.14.0 or later.

Based on closed encode/httpx issue #1082 · 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
@@ -311,7 +311,8 @@ def get_environment_proxies() -> typing.Dict[str, typing.Optional[str]]: for scheme in ("http", "https", "all"): if proxy_info.get(scheme): - mounts[scheme] = proxy_info[scheme] + hostname = proxy_info[scheme] + mounts[scheme] = hostname if "://" in hostname else f"http://{hostname}"
repro.py
~/projects » python3 hejl@hejldeIMAC Python 3.8.4 (default, Jul 14 2020, 02:58:48) [Clang 11.0.3 (clang-1103.0.32.62)] on darwin Type "help", "copyright", "credits" or "license" for more information. >> import httpx >> httpx.get("https://www.github.com") Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/local/lib/python3.8/site-packages/httpx/_api.py", line 159, in get return request( File "/usr/local/lib/python3.8/site-packages/httpx/_api.py", line 83, in request with Client( File "/usr/local/lib/python3.8/site-packages/httpx/_client.py", line 467, in __init__ proxy_map = self.get_proxy_map(proxies, trust_env) File "/usr/local/lib/python3.8/site-packages/httpx/_client.py", line 87, in get_proxy_map return { File "/usr/local/lib/python3.8/site-packages/httpx/_client.py", line 88, in <dictcomp> key: Proxy(url=url) File "/usr/local/lib/python3.8/site-packages/httpx/_config.py", line 335, in __init__ url = URL(url) File "/usr/local/lib/python3.8/site-packages/httpx/_models.py", line 90, in __init__ raise InvalidURL("No scheme included in URL.") httpx._exceptions.InvalidURL: No scheme included in URL.
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\nUpgrade to version 0.14.0 or later.\nWhen NOT to use: This fix is not suitable if the application requires strict URL validation without defaults.\n\n

Why This Fix Works in Production

  • Trigger: ~/projects » python3 hejl@hejldeIMAC
  • Mechanism: The proxy environment variable lacks a scheme, causing URL validation to fail
  • Why the fix works: Handles bare environment proxy hostnames gracefully by auto-prepending 'http://' if no scheme is provided. (first fixed release: 0.14.0).
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.8.4 in real deployments (not just unit tests).
  • The proxy environment variable lacks a scheme, causing URL validation to fail
  • Surfaces as: ~/projects » python3 hejl@hejldeIMAC

Proof / Evidence

  • GitHub issue: #1082
  • Fix PR: https://github.com/encode/httpx/pull/1120
  • First fixed release: 0.14.0
  • 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.23

Discussion

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

Jump to Sources Open on GitHub
“FYI, after the drop of URL(allow_relative=bool) in #1073, proxy without explicit schema will cause ValueError: Unknown scheme for proxy URL URL('127.0.0.1:7890') instead.”
@j178 · 2020-07-29 · source
“@j178 I wouldn't mind making sure we've got a decent UX around handling that case. Are you seeing that when using the proxies=... style, or…”
@lovelydinosaur · 2020-07-29 · source
“Right, not entirely clear if we should aim to be lenient to this, or if we should just make sure the error is as clear…”
@lovelydinosaur · 2020-07-29 · source
“Another useful data point here would be - what does curl do when issuing a request if ALL_PROXY includes a bare hostname?”
@lovelydinosaur · 2020-07-31 · source

Failure Signature (Search String)

  • ~/projects » python3 hejl@hejldeIMAC

Error Message

Stack trace
error.txt
Error Message ------------- ~/projects » python3 hejl@hejldeIMAC Python 3.8.4 (default, Jul 14 2020, 02:58:48) [Clang 11.0.3 (clang-1103.0.32.62)] on darwin Type "help", "copyright", "credits" or "license" for more information. >> import httpx >> httpx.get("https://www.github.com") Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/local/lib/python3.8/site-packages/httpx/_api.py", line 159, in get return request( File "/usr/local/lib/python3.8/site-packages/httpx/_api.py", line 83, in request with Client( File "/usr/local/lib/python3.8/site-packages/httpx/_client.py", line 467, in __init__ proxy_map = self.get_proxy_map(proxies, trust_env) File "/usr/local/lib/python3.8/site-packages/httpx/_client.py", line 87, in get_proxy_map return { File "/usr/local/lib/python3.8/site-packages/httpx/_client.py", line 88, in <dictcomp> key: Proxy(url=url) File "/usr/local/lib/python3.8/site-packages/httpx/_config.py", line 335, in __init__ url = URL(url) File "/usr/local/lib/python3.8/site-packages/httpx/_models.py", line 90, in __init__ raise InvalidURL("No scheme included in URL.") httpx._exceptions.InvalidURL: No scheme included in URL.
Stack trace
error.txt
Error Message ------------- >> import os >> os.environ['all_proxy'] = '127.0.0.1:7890' >> import httpx >> httpx.get('https://github.com') Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/home/johnj/.pyenv/versions/general/lib/python3.7/site-packages/httpx/_api.py", line 170, in get trust_env=trust_env, File "/home/johnj/.pyenv/versions/general/lib/python3.7/site-packages/httpx/_api.py", line 84, in request cert=cert, verify=verify, timeout=timeout, trust_env=trust_env, File "/home/johnj/.pyenv/versions/general/lib/python3.7/site-packages/httpx/_client.py", line 463, in __init__ proxy_map = self._get_proxy_map(proxies, trust_env) File "/home/johnj/.pyenv/versions/general/lib/python3.7/site-packages/httpx/_client.py", line 93, in _get_proxy_map for key, url in get_environment_proxies().items() File "/home/johnj/.pyenv/versions/general/lib/python3.7/site-packages/httpx/_client.py", line 93, in <dictcomp> for key, url in get_environment_proxies().items() File "/home/johnj/.pyenv/versions/general/lib/python3.7/site-packages/httpx/_config.py", line 326, in __init__ raise ValueError(f"Unknown scheme for proxy URL {url!r}") ValueError: Unknown scheme for proxy URL URL('127.0.0.1:7890') >> os.environ.pop('all_proxy') '127.0.0.1:7890' >> client = httpx.Client(proxies='127.0.0.1:7890') Traceback (most recent call last): File "<stdin>", line 1, in < ... (truncated) ...

Minimal Reproduction

repro.py
~/projects » python3 hejl@hejldeIMAC Python 3.8.4 (default, Jul 14 2020, 02:58:48) [Clang 11.0.3 (clang-1103.0.32.62)] on darwin Type "help", "copyright", "credits" or "license" for more information. >> import httpx >> httpx.get("https://www.github.com") Traceback (most recent call last): File "<stdin>", line 1, in <module> File "/usr/local/lib/python3.8/site-packages/httpx/_api.py", line 159, in get return request( File "/usr/local/lib/python3.8/site-packages/httpx/_api.py", line 83, in request with Client( File "/usr/local/lib/python3.8/site-packages/httpx/_client.py", line 467, in __init__ proxy_map = self.get_proxy_map(proxies, trust_env) File "/usr/local/lib/python3.8/site-packages/httpx/_client.py", line 87, in get_proxy_map return { File "/usr/local/lib/python3.8/site-packages/httpx/_client.py", line 88, in <dictcomp> key: Proxy(url=url) File "/usr/local/lib/python3.8/site-packages/httpx/_config.py", line 335, in __init__ url = URL(url) File "/usr/local/lib/python3.8/site-packages/httpx/_models.py", line 90, in __init__ raise InvalidURL("No scheme included in URL.") httpx._exceptions.InvalidURL: No scheme included in URL.

Environment

  • Python: 3.8.4

What Broke

Users encounter an InvalidURL error when using a bare hostname in proxy settings.

Why It Broke

The proxy environment variable lacks a scheme, causing URL validation to fail

Fix Options (Details)

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

Upgrade to version 0.14.0 or later.

When NOT to use: This fix is not suitable if the application requires strict URL validation without defaults.

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

Fix reference: https://github.com/encode/httpx/pull/1120

First fixed release: 0.14.0

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 is not suitable if the application requires strict URL validation without defaults.

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
0.14.0 Fixed

Related Issues

No related fixes found.

Cluster: httpx:configuration-error All hubs All clusters
Related clusters: Data consistency Other Timeout

Sources

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

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