The Fix
Upgrade to version 0.28.0 or later.
Based on closed Kludex/starlette issue #493 · 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%.
@@ -0,0 +1,76 @@
@@ -0,0 +1,76 @@
+import typing
+
+from starlette._utils import is_async_callable
repro.py
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.exceptions import HTTPException
from json.decoder import JSONDecodeError
import uvicorn
# Force an exception sending an invalid json to "/"
# it will trigger an exception and it will be handled
# by log_exceptions and the assert will trigger an
# exception because request.body() cannot be read
# anymore (stream already consumed)
app = Starlette(debug=True)
@app.exception_handler(JSONDecodeError)
async def log_exceptions(request, exc):
body: bytes = await request.body() # hangs forever
body_text: str = bytes.decode(body)
assert body_text, "I could not retrieve the body"
return JSONResponse({ "error": "Unexpected error happened!" })
@app.route('/', methods=["POST"])
async def homepage(request):
body_bytes = await request.body()
if body_bytes:
json = await request.json()
return JSONResponse(json)
return JSONResponse({ "error": "empty body, please send something" })
if __name__ == '__main__':
uvicorn.run(app, host='0.0.0.0', port=8000)
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.28.0 or later.\nWhen NOT to use: This fix should not be used if the request body needs to be read multiple times.\n\n
Why This Fix Works in Production
- Trigger: Hi dears developers, how can I retrieve the request.body inside an exception_handler?
- Mechanism: The request body is consumed during JSON parsing, preventing access in exception handlers
- Why the fix works: upstream changes in 0.28.0 address the mechanism above.
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 request body is consumed during JSON parsing, preventing access in exception handlers
- Production symptom (often without a traceback): Hi dears developers, how can I retrieve the request.body inside an exception_handler?
Proof / Evidence
- GitHub issue: #493
- Fix PR: https://github.com/kludex/starlette/pull/2026
- First fixed release: 0.28.0
- Reproduced locally: No (not executed)
- Last verified: 2026-02-09
- Confidence: 0.60
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.43
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“Any movements? Without this functionality, we don't have access to origin request on exception handler. This is really strange.”
“Any news? Still having the hanging issue.”
“What’s the simplest possible code sample someone could use to replicate the issue? (Ideally just using Starlette itself if possible)”
“I expect there’s an issue with the request body already having been streamed, but we ought to be able to handle things more gracefully.”
Failure Signature (Search String)
- Hi dears developers, how can I retrieve the request.body inside an exception_handler?
- https://github.com/encode/starlette/blob/d23bfd0d8ff68d535d0283aa4099e5055da88bb9/starlette/exceptions.py#L79
Copy-friendly signature
signature.txt
Failure Signature
-----------------
Hi dears developers, how can I retrieve the request.body inside an exception_handler?
https://github.com/encode/starlette/blob/d23bfd0d8ff68d535d0283aa4099e5055da88bb9/starlette/exceptions.py#L79
Error Message
Signature-only (no traceback captured)
error.txt
Error Message
-------------
Hi dears developers, how can I retrieve the request.body inside an exception_handler?
https://github.com/encode/starlette/blob/d23bfd0d8ff68d535d0283aa4099e5055da88bb9/starlette/exceptions.py#L79
Minimal Reproduction
repro.py
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.exceptions import HTTPException
from json.decoder import JSONDecodeError
import uvicorn
# Force an exception sending an invalid json to "/"
# it will trigger an exception and it will be handled
# by log_exceptions and the assert will trigger an
# exception because request.body() cannot be read
# anymore (stream already consumed)
app = Starlette(debug=True)
@app.exception_handler(JSONDecodeError)
async def log_exceptions(request, exc):
body: bytes = await request.body() # hangs forever
body_text: str = bytes.decode(body)
assert body_text, "I could not retrieve the body"
return JSONResponse({ "error": "Unexpected error happened!" })
@app.route('/', methods=["POST"])
async def homepage(request):
body_bytes = await request.body()
if body_bytes:
json = await request.json()
return JSONResponse(json)
return JSONResponse({ "error": "empty body, please send something" })
if __name__ == '__main__':
uvicorn.run(app, host='0.0.0.0', port=8000)
What Broke
Exception handlers hang when trying to read the request body after it has been consumed.
Why It Broke
The request body is consumed during JSON parsing, preventing access in exception handlers
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 0.28.0 or later.
When NOT to use: This fix should not be used if the request body needs to be read multiple times.
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
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)
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)
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/2026
First fixed release: 0.28.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix should not be used if the request body needs to be read multiple times.
- 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.
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
- 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.28.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.