The Fix
Upgrade to version 0.26.0 or later.
Based on closed Kludex/starlette issue #608 · 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%.
@@ -106,8 +106,9 @@ def build_middleware_stack(self) -> ASGIApp:
return self.router.routes
- def url_path_for(self, name: str, **path_params: typing.Any) -> URLPath:
- return self.router.url_path_for(name, **path_params)
+ # TODO: Make `__name` a positional-only argument when we drop Python 3.7 support.
Option A — Upgrade to fixed release\nUpgrade to version 0.26.0 or later.\nWhen NOT to use: Do not use this fix if your application relies on the previous behavior of url_for().\n\nOption C — Workaround\nI have renamed the path variable in my API, but `name` was really fitting, and what I wanted to use, and not at all an uncommon variable name.\nWhen NOT to use: Do not use this fix if your application relies on the previous behavior of url_for().\n\n
Why This Fix Works in Production
- Trigger: TypeError: url_for() got multiple values for argument 'name'
- Mechanism: The 'name' argument in url_for() conflicts with path parameters, causing TypeError
- Why the fix works: Allows the 'name' argument on the url_for() and url_path_for() methods, resolving the issue of multiple values for the 'name' argument. (first fixed release: 0.26.0).
- 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 'name' argument in url_for() conflicts with path parameters, causing TypeError
- Surfaces as: TypeError: url_for() got multiple values for argument 'name'
Proof / Evidence
- GitHub issue: #608
- Fix PR: https://github.com/kludex/starlette/pull/2050
- First fixed release: 0.26.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.77
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“I was hit by that issue just today and would like to see it merged.”
“I’d suggest we change it to an unnamed argument. We could do this by changing the argument signature to *args, **kwargs, and ensuring that len(args)…”
“PR: https://github.com/encode/starlette/pull/611”
“Had a problem here too and took me around 30mins to find out why. Looked if there is an issue: Yeah. It is. Since 2019.”
Failure Signature (Search String)
- TypeError: url_for() got multiple values for argument 'name'
Error Message
Stack trace
Error Message
-------------
TypeError: url_for() got multiple values for argument 'name'
What Broke
Users experience TypeError when using url_for() with 'name' in path parameters.
Why It Broke
The 'name' argument in url_for() conflicts with path parameters, causing TypeError
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 0.26.0 or later.
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Option C — Workaround Temporary workaround
I have renamed the path variable in my API, but `name` was really fitting, and what I wanted to use, and not at all an uncommon variable name.
Use only if you cannot change versions today. Treat this as a stopgap and remove once upgraded.
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)
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)
Fix reference: https://github.com/kludex/starlette/pull/2050
First fixed release: 0.26.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- Do not use this fix if your application relies on the previous behavior of url_for().
- 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.
Version Compatibility Table
| Version | Status |
|---|---|
| 0.26.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.