fix(upload): answer a failing upload handler with a 500 or an error frame

Merged
MA
5d ago
+381-10

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):

handler0.10.10.11.0a1
writes state, then raises (the finding's case)granian's bare 500200, delta, truncated
yields, then raises200, delta, truncated200, delta, truncated
raises with no writesgranian's bare 500granian's bare 500
any failure, token's first request (hydrate delta first)truncatedtruncated

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.py has an upload-only _UploadStreamingResponse, a DisconnectAwareStreamingResponse subclass that holds http.response.start until 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_updates catches 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.
  • 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 logs Error parsing chunk ... before Upload error: HTTP error! status: <code>.
  • EventProcessor._resolve_future keeps 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 through httpx.ASGITransport, which re-raises anything that escapes the app. Main: OSError: File name too long escapes. Fixed: status 500, one backend exception handler call, and its traceback contains failing_upload.
  • tests/units/test_app.py::test_upload_handler_error_after_update_ends_stream_with_error_frame. Main: the OSError escapes. Fixed: status 200, the update frame, then a final {"error": ...} frame, one handler call that names yield_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 the with_traceback(tb) restore reverted.
  • tests/units/reflex_base/client_upload.mjs (via test_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.log also gets Error parsing chunk with a SyntaxError.

Also run:

  • uv run pytest tests/units --cov (excluding tests/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".
  • 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" RuntimeError is still caught, though the processor never reported it. It can't occur while the route is served, since configure runs in the same lifespan step that creates the processor.
  • Tests sit next to the existing upload tests (tests/units/test_app.py, and the client_upload.mjs harness that already loads upload.js with a stubbed env.json), not in new module-named files or tests/js/.
  • Background (chunk) upload handlers answer 202 at once and are unchanged.

Generated by Claude Code