httpx `params` overrides query string in url (Fix)

The Fix

Upgrade to version 0.13.0 or later.

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

@@ -90,9 +90,14 @@ def __init__(
             self._uri_reference = self._uri_reference.normalize()
 
-        # Add any query parameters.
+        # Add any query parameters, merging with any in the URL if needed.
         if params:

repro.py

import requests
import httpx
import asyncio

URL = 'https://httpbin.org/get?a=1'

r = requests.get(URL, params={'b': 2})
print('requests', r.json()['args'])

async def f():
    r = await httpx.get(URL, params={'b': 2})
    print('httpx', r.json()['args'])
asyncio.run(f())

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.13.0 or later.\nWhen NOT to use: This fix should not be used if the intended behavior is to replace existing query parameters.\n\n

Why This Fix Works in Production

Trigger: Query parameters provided in `params` are not included in the final request URL, leading to incorrect behavior.
Mechanism: The `params` argument replaces existing query parameters instead of merging them
Why the fix works: `params` argument on URL should merge with existing query parameters instead of replacing them. (first fixed release: 0.13.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

The `params` argument replaces existing query parameters instead of merging them
Production symptom (often without a traceback): Query parameters provided in `params` are not included in the final request URL, leading to incorrect behavior.

Proof / Evidence

GitHub issue: #652
Fix PR: https://github.com/encode/httpx/pull/653
First fixed release: 0.13.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.65

Discussion

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

Jump to Sources Open on GitHub

“Not intentional, nope. It looks like we need to make sure the merge_queryparams also accepts the url, and includes any query params that are included…”

@lovelydinosaur · 2019-12-20 · source

“On second thoughts, we should actually be handling that bit on the URL class itself”

@lovelydinosaur · 2019-12-20 · source

Failure Signature (Search String)

Query parameters provided in `params` are not included in the final request URL, leading to incorrect behavior.

Copy-friendly signature

signature.txt

Failure Signature
-----------------
Query parameters provided in `params` are not included in the final request URL, leading to incorrect behavior.

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
Query parameters provided in `params` are not included in the final request URL, leading to incorrect behavior.

Minimal Reproduction

repro.py

import requests
import httpx
import asyncio

URL = 'https://httpbin.org/get?a=1'

r = requests.get(URL, params={'b': 2})
print('requests', r.json()['args'])

async def f():
    r = await httpx.get(URL, params={'b': 2})
    print('httpx', r.json()['args'])
asyncio.run(f())

What Broke

Query parameters provided in `params` are not included in the final request URL, leading to incorrect behavior.

Why It Broke

The `params` argument replaces existing query parameters instead of merging them

Fix Options (Details)

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

Upgrade to version 0.13.0 or later.

When NOT to use: This fix should not be used if the intended behavior is to replace existing query parameters.

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

First fixed release: 0.13.0

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

When NOT to Use This Fix

This fix should not be used if the intended behavior is to replace existing query parameters.

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.13.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.