starlette QueryParams unexpected bahavior (Fix)

The Fix

Ensures that QueryParams behavior matches standard mappings by modifying the keys, values, and items methods to return unique keys and their last values.

Based on closed Kludex/starlette issue #333 · PR/commit linked

Production note: This usually shows up under retries/timeouts. Treat it as a side-effect risk until you can verify behavior with a canary + real traffic.

Open PR/Commit

@@ -231,7 +231,7 @@ class QueryParams(typing.Mapping[str, str]):
     def __init__(
         self,
-        params: typing.Mapping[str, str] = None,
+        params: typing.Union["QueryParams", typing.Mapping[str, str]] = None,
         items: typing.List[typing.Tuple[str, str]] = None,

fix.md

Option A — Apply the official fix\nEnsures that QueryParams behavior matches standard mappings by modifying the keys, values, and items methods to return unique keys and their last values.\nWhen NOT to use: Do not use this fix if maintaining duplicate key behavior is required for your application.\n\n

Why This Fix Works in Production

Trigger: QueryParams unexpected bahavior
Mechanism: QueryParams methods return duplicate keys and values instead of unique keys with their last values

Production impact:

If left unfixed, this can cause silent data inconsistencies that propagate (bad cache entries, incorrect downstream decisions).

Why This Breaks in Prod

QueryParams methods return duplicate keys and values instead of unique keys with their last values
Production symptom (often without a traceback): QueryParams unexpected bahavior

Proof / Evidence

GitHub issue: #333
Fix PR: https://github.com/kludex/starlette/pull/338
Reproduced locally: No (not executed)
Last verified: 2026-02-12
Confidence: 0.70
Did this fix it?: Yes (upstream fix exists)
Own content ratio: 0.81

Discussion

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

Jump to Sources Open on GitHub

“Let's treat this as two different issues. 1. Yup, perfectly happy to have the single-value variants instead. 2. Perhaps we'll have a base class too,…”

@lovelydinosaur · 2019-01-22 · source

“@tomchristie you want .keys() to return a generator, a dict_keys or a list ?”

@taoufik07 · 2019-01-22 · source

“I'd suggest just starting with a list, as it currently is. QueryParams have a limited size, so that'll be just fine. I'd be okay with…”

@lovelydinosaur · 2019-01-22 · source

Failure Signature (Search String)

QueryParams unexpected bahavior

Copy-friendly signature

signature.txt

Failure Signature
-----------------
QueryParams unexpected bahavior

Error Message

Signature-only (no traceback captured)

error.txt

Error Message
-------------
QueryParams unexpected bahavior

What Broke

Users experience unexpected behavior when retrieving query parameters, leading to confusion and potential data handling issues.

Why It Broke

QueryParams methods return duplicate keys and values instead of unique keys with their last values

Fix Options (Details)

Option A — Apply the official fix

Ensures that QueryParams behavior matches standard mappings by modifying the keys, values, and items methods to return unique keys and their last values.

When NOT to use: Do not use this fix if maintaining duplicate key behavior is required for your application.

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.
This does NOT fix data corruption; it only prevents duplicate side-effects.

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)

See OnceOnly SDK

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/kludex/starlette/pull/338

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

When NOT to Use This Fix

Do not use this fix if maintaining duplicate key behavior is required for your application.
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.

Did This Fix Work in Your Case?

Quick signal helps us prioritize which fixes to verify and improve.

Prevention

Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
Pin production dependencies and upgrade only with a reproducible test that hits the failing path.

Related Issues

No related fixes found.

Cluster: starlette:data-consistency All hubs All clusters

Related clusters: Configuration error SSL handshake Other

Sources

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