httpx Some URLs with unescaped query strings cannot resolve

The Fix

Upgrade to version 0.24.0 or later.

Based on closed encode/httpx issue #1833 · 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

@@ -128,8 +128,7 @@ The HTTPX project relies on these excellent libraries:
   * `h11` - HTTP/1.1 support.
 * `certifi` - SSL certificates.
-* `rfc3986` - URL parsing & normalization.
-  * `idna` - Internationalized domain name support.
+* `idna` - Internationalized domain name support.

repro.py

>> httpx.URL("https://example.com/?[]").join("/")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/tomchristie/GitHub/encode/httpx/httpx/_models.py", line 574, in join
    return URL(relative_url._uri_reference.resolve_with(base_uri).unsplit())
  File "/Users/tomchristie/GitHub/encode/httpx/venv/lib/python3.6/site-packages/rfc3986/_mixin.py", line 266, in resolve_with
    raise exc.ResolutionError(base_uri)
rfc3986.exceptions.ResolutionError: https://example.com/?[] is not an absolute URI.

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.24.0 or later.\nWhen NOT to use: This fix may not be suitable if strict RFC3986 compliance is required.\n\n

Why This Fix Works in Production

Trigger: return await self.request(
Mechanism: The rfc3986 package fails to resolve certain URLs with unescaped query strings
Why the fix works: Drops the `rfc3986` package dependency, in favor of a carefully worked through `urlparse` implementation, addressing issues with URL parsing and normalization. (first fixed release: 0.24.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.6 in real deployments (not just unit tests).
The rfc3986 package fails to resolve certain URLs with unescaped query strings
Surfaces as: File "httpx/_client.py", line 1776, in head

Proof / Evidence

GitHub issue: #1833
Fix PR: https://github.com/encode/httpx/pull/2252
First fixed release: 0.24.0
Reproduced locally: No (not executed)
Last verified: 2026-02-08
Confidence: 0.85
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.33

Discussion

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

Jump to Sources Open on GitHub

“This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank…”

@stale · 2022-02-20 · source

“I played with it a bit and the change did fail some tests and these cases seem legit”

@kangzhang · 2021-09-03 · source

Failure Signature (Search String)

return await self.request(

Error Message

Stack trace

error.txt

Error Message
-------------
File "httpx/_client.py", line 1776, in head
    return await self.request(
  File "httpx/_client.py", line 1481, in request
    response = await self.send(
  File "httpx/_client.py", line 1568, in send
    response = await self._send_handling_auth(
  File "httpx/_client.py", line 1604, in _send_handling_auth
    response = await self._send_handling_redirects(
  File "httpx/_client.py", line 1658, in _send_handling_redirects
    raise exc
  File "httpx/_client.py", line 1647, in _send_handling_redirects
    request = self._build_redirect_request(request, response)
  File "httpx/_client.py", line 456, in _build_redirect_request
    url = self._redirect_url(request, response)
  File "httpx/_client.py", line 508, in _redirect_url
    url = request.url.join(url)
  File "httpx/_models.py", line 573, in join
    return URL(relative_url._uri_reference.resolve_with(base_uri).unsplit())
  File "rfc3986/_mixin.py", line 266, in resolve_with
    raise exc.ResolutionError(base_uri)

Stack trace

error.txt

Error Message
-------------
>> httpx.URL("https://example.com/?[]").join("/")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/tomchristie/GitHub/encode/httpx/httpx/_models.py", line 574, in join
    return URL(relative_url._uri_reference.resolve_with(base_uri).unsplit())
  File "/Users/tomchristie/GitHub/encode/httpx/venv/lib/python3.6/site-packages/rfc3986/_mixin.py", line 266, in resolve_with
    raise exc.ResolutionError(base_uri)
rfc3986.exceptions.ResolutionError: https://example.com/?[] is not an absolute URI.

Minimal Reproduction

repro.py

>> httpx.URL("https://example.com/?[]").join("/")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/tomchristie/GitHub/encode/httpx/httpx/_models.py", line 574, in join
    return URL(relative_url._uri_reference.resolve_with(base_uri).unsplit())
  File "/Users/tomchristie/GitHub/encode/httpx/venv/lib/python3.6/site-packages/rfc3986/_mixin.py", line 266, in resolve_with
    raise exc.ResolutionError(base_uri)
rfc3986.exceptions.ResolutionError: https://example.com/?[] is not an absolute URI.

Environment

Python: 3.6

What Broke

Users experience crashes when resolving relative redirects for specific URLs.

Why It Broke

The rfc3986 package fails to resolve certain URLs with unescaped query strings

Fix Options (Details)

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

Upgrade to version 0.24.0 or later.

When NOT to use: This fix may not be suitable if strict RFC3986 compliance is required.

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

First fixed release: 0.24.0

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

When NOT to Use This Fix

This fix may not be suitable if strict RFC3986 compliance is required.

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.

Version Compatibility Table

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

httpx Some URLs with unescaped query strings cannot resolve relative redirects. (Fix)