The Fix
Upgrade to version 0.21.0 or later.
Based on closed Kludex/starlette issue #1029 · PR/commit linked
@@ -232,6 +232,280 @@ around explicitly, rather than mutating the middleware instance.
- Using `BaseHTTPMiddleware` will prevent changes to [`contextlib.ContextVar`](https://docs.python.org/3/library/contextvars.html#contextvars.ContextVar)s from propagating upwards. That is, if you set a value for a `ContextVar` in your endpoint and try to read it from a middleware you will find that the value is not the same value you set in your endpoint (see [this test](https://github.com/encode/starlette/blob/621abc747a6604825190b93467918a0ec6456a24/tests/middleware/test_base.py#L192-L223) for an example of this behavior).
+## Pure ASGI Middleware
+
+Thanks to how ASGI was designed, it is possible to implement middleware as a chain of ASGI applications, where each application calls into the next one.
Option A — Upgrade to fixed release\nUpgrade to version 0.21.0 or later.\nWhen NOT to use: Avoid using BaseHTTPMiddleware with StreamingResponse or FileResponse endpoints.\n\n
Why This Fix Works in Production
- Trigger: Developers faced confusion and implementation issues when using BaseHTTPMiddleware incorrectly.
- Mechanism: Documentation lacked guidance on using BaseHTTPMiddleware with ASGI middleware
- Why the fix works: Improved documentation on creating ASGI middleware and the limitations of BaseHTTPMiddleware. (first fixed release: 0.21.0).
Why This Breaks in Prod
- Documentation lacked guidance on using BaseHTTPMiddleware with ASGI middleware
- Production symptom (often without a traceback): Developers faced confusion and implementation issues when using BaseHTTPMiddleware incorrectly.
Proof / Evidence
- GitHub issue: #1029
- Fix PR: https://github.com/kludex/starlette/pull/1656
- First fixed release: 0.21.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.52
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“I think we should also document on how to create middlewares without BaseHTTPMiddleware.”
Failure Signature (Search String)
- Developers faced confusion and implementation issues when using BaseHTTPMiddleware incorrectly.
Copy-friendly signature
Failure Signature
-----------------
Developers faced confusion and implementation issues when using BaseHTTPMiddleware incorrectly.
Error Message
Signature-only (no traceback captured)
Error Message
-------------
Developers faced confusion and implementation issues when using BaseHTTPMiddleware incorrectly.
What Broke
Developers faced confusion and implementation issues when using BaseHTTPMiddleware incorrectly.
Why It Broke
Documentation lacked guidance on using BaseHTTPMiddleware with ASGI middleware
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 0.21.0 or later.
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Fix reference: https://github.com/kludex/starlette/pull/1656
First fixed release: 0.21.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- Avoid using BaseHTTPMiddleware with StreamingResponse or FileResponse endpoints.
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.21.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.