fix(upload): answer a failing upload handler with a 500 or an error frame
All Submissions:
- Have you followed the guidelines stated in CONTRIBUTING.md file?
- Have you checked to ensure there aren't any other open Pull Requests for the desired changed?
Type of change
- Bug fix (non-breaking change which fixes an issue)
Changes To Core Features:
- Have you added an explanation of what your changes do and why you'd like us to include them?
- Have you written new tests for your core changes, as applicable?
- Have you successfully ran tests with your changes locally?
Release fix-up for FINDING-044 from the reflex 0.11.0a1 pre-release testing (artifacts on branch claude/vibrant-pasteur-3921g3, prerelease-testing/runs/2026-11-11-v0.11.0a1/).
Defect
If an upload handler raises, the exception escapes the streamed /_upload response. The ASGI server cuts the chunked body mid-stream (ERR_INCOMPLETE_CHUNKED_ENCODING, httpx incomplete chunked read) and logs the exception a second time ("Application callable raised an exception", after the backend exception handler's [Reflex Backend Exception]). Neither log names the handler: the upload stream awaits the event's future and re-raises the exception before the backend exception handler task runs, and that re-raise replaces the traceback, leaving only _wait_for_chain / wait_all frames. (CPython's C asyncio.Future gives an awaited exception only the awaiting frames.)
Behaviour compared on PyPI 0.10.1 and 0.11.0a1 (granian, dev mode, warm token, raw curl --raw):
| handler | 0.10.1 | 0.11.0a1 |
|---|---|---|
| writes state, then raises (the finding's case) | granian's bare 500 | 200, delta, truncated |
| yields, then raises | 200, delta, truncated | 200, delta, truncated |
| raises with no writes | granian's bare 500 | granian's bare 500 |
| any failure, token's first request (hydrate delta first) | truncated | truncated |
The behaviour change comes from #7696 (merged after 0.10.1). It streams a failing handler's writes before the exception propagates, so the body has already started when the exception arrives. #7721 changed only how upload.js parses chunks. Granian holds http.response.start until the first body message, so 0.10.1 got a 500 only when nothing had been streamed. That 500 came from granian itself and had no CORS headers.
In the browser (rx.upload + rx.upload_files, Chromium) the UX was the same in both versions. The backend exception handler's error toast arrives over the websocket, the written state is applied and on_upload_progress reaches 1. upload.js then logs Upload error: Network error to the console: for 0.10.1 because CORS blocks the 500, for 0.11.0a1 because the chunked body is incomplete. So users don't see a regression; the problems are on the wire and in the logs.
Fix
_upload.pyhas an upload-only_UploadStreamingResponse, aDisconnectAwareStreamingResponsesubclass that holdshttp.response.startuntil the first body message. A body that fails before yielding can then still be answered with an error status. Because it lives in reflex-components-core, the fix also works with the published reflex-base 0.11.0a1; I checked that by hand.- The upload stream
_ndjson_updatescatches the handler's exception from the event processor's stream, which the processor has already reported:- before any update was sent:
HTTPException(500). Starlette answers it inside the CORS middleware, so the browser can read the status; - after an update: the stream ends cleanly with
{"error": "The upload handler raised an exception."}. The message is generic because the details go to the backend exception handler, and in prod that handler says only "contact the administrator". - Nothing escapes to the server, so the exception is logged once.
- The catch covers only
anext()of the stream. Serializing an update,app.event_processor, and a processor that isn't running (QueueShutDown) fail outside it, so the server still logs those.
- before any update was sent:
upload.js: when it sees an error frame it rejects the upload (Upload error: <message>) and does not pass the frame to the state listener. It parses chunks only from a 2xx response, so the plain-text body of the 500 (or of a 400 such as "Unknown upload event handler") no longer logsError parsing chunk ...beforeUpload error: HTTP error! status: <code>.EventProcessor._resolve_futurekeeps the traceback the handler raised with and restores it in the handler task, so[Reflex Backend Exception]shows the handler's frame (upapp.py, line 21, in fail_nowrite).
Test plan
Failing before the fix (run with the source files checked out from origin/main), passing after:
tests/units/test_app.py::test_upload_handler_error_before_any_update_returns_500: a real Starlette route throughhttpx.ASGITransport, which re-raises anything that escapes the app. Main:OSError: File name too longescapes. Fixed: status 500, one backend exception handler call, and its traceback containsfailing_upload.tests/units/test_app.py::test_upload_handler_error_after_update_ends_stream_with_error_frame. Main: theOSErrorescapes. Fixed: status 200, the update frame, then a final{"error": ...}frame, one handler call that namesyield_then_fail_upload.tests/units/test_app.py::test_upload_error_the_event_processor_did_not_report_reaches_the_server(QueueShutDown, an update that fails to serialize): both fail on 5d91c16ae, where they were swallowed. Both now escape to the server.tests/units/reflex_base/event/processor/test_event_processor.py::test_backend_exception_handler_sees_handler_frames_when_future_awaited. Main:'_error_handler' in ['test_backend_exception_handler_sees_...']fails. It also fails with only thewith_traceback(tb)restore reverted.tests/units/reflex_base/client_upload.mjs(viatest_client_event_queue.py), "an error frame ending the stream fails the upload, not the listener". Main: the upload resolves with the response and the listener gets the error frame.tests/units/reflex_base/client_upload.mjs, "an error response fails the upload by its status, not as a chunk" (a 500 with a plain-text body). Before the 2xx check:console.logalso getsError parsing chunkwith aSyntaxError.
Also run:
uv run pytest tests/units --cov(excludingtests/units/reflex_bench/drivers/test_browser.py: no Chromium for pytest-playwright in this environment): 15639 passed, 66 skipped, coverage 81.46%.ruff check,ruff format,pyright reflex tests(0 errors) and the pre-commit hooks on the changed files (biome, ty) all pass.npm --prefix tests/js test: 29 passed.- Browser check of the fix, with the worktree installed in a 0.11.0a1-style app:
- no-write failure: readable 500 with CORS headers, console
Upload error: HTTP error! status: 500; - write-then-raise and yield-then-raise: 200 that ends with the error frame, console
Upload error: The upload handler raised an exception., no failed request; - toast and state the same as before;
- server log: one
[Reflex Backend Exception]that names the handler, zero granian "Application callable raised".
- no-write failure: readable 500 with CORS headers, console
- Same raw check with this branch's reflex-components-core over the published reflex-base 0.11.0a1: 500 / error frame, no granian log.
Notes
- A handler that writes state before raising now gets 200 plus an error frame, not 500, because its writes are streamed first (#7696). A non-browser client has to check the last frame.
- enqueue_stream_delta's "not configured"
RuntimeErroris still caught, though the processor never reported it. It can't occur while the route is served, sinceconfigureruns in the same lifespan step that creates the processor. - Tests sit next to the existing upload tests (
tests/units/test_app.py, and theclient_upload.mjsharness that already loadsupload.jswith a stubbedenv.json), not in new module-named files ortests/js/. - Background (chunk) upload handlers answer 202 at once and are unchanged.
Generated by Claude Code