{"record":{"id":"d88bef6119e735d1","repo":"reflex-dev/reflex","slug":"rx-event-background-true-is-not-supported-for-up","errorCode":null,"errorMessage":"@rx.event(background=True) is not supported for upload handler `{handler_name}`.","messagePattern":"@rx\\.event\\(background=True\\) is not supported for upload handler `(.+?)`\\.","errorType":"exception","errorClass":"UploadTypeError","httpStatus":null,"severity":"error","filePath":"packages/reflex-base/src/reflex_base/event/__init__.py","lineNumber":345,"sourceCode":"\n    Returns:\n        The parameter name and annotation for the upload file argument.\n\n    Raises:\n        UploadTypeError: If the handler is a background task.\n        UploadValueError: If the handler does not accept ``list[rx.UploadFile]``.\n    \"\"\"\n    from reflex_components_core.core._upload import UploadFile\n\n    from reflex_base.utils.exceptions import UploadTypeError, UploadValueError\n\n    handler_name = _handler_name(handler)\n    if handler.is_background:\n        msg = (\n            f\"@rx.event(background=True) is not supported for upload handler \"\n            f\"`{handler_name}`.\"\n        )\n        raise UploadTypeError(msg)\n\n    for name, annotation in handler._get_type_hints().items():\n        if name == \"return\" or get_origin(annotation) is not list:\n            continue\n        args = get_args(annotation)\n        if len(args) == 1 and typehint_issubclass(args[0], UploadFile):\n            return name, annotation\n\n    msg = (\n        f\"`{handler_name}` handler should have a parameter annotated as \"\n        \"list[rx.UploadFile]\"\n    )\n    raise UploadValueError(msg)\n\n\ndef resolve_upload_chunk_handler_param(handler: \"EventHandler\") -> tuple[str, type]:\n    \"\"\"Validate and resolve the UploadChunkIterator parameter for a handler.\n","sourceCodeStart":327,"sourceCodeEnd":363,"githubUrl":"https://github.com/reflex-dev/reflex/blob/45b8ed5ab735f8a56bbb09a42384f030eb0208e7/packages/reflex-base/src/reflex_base/event/__init__.py#L327-L363","documentation":"Upload handlers (used with rx.upload_file) run in a dedicated request context, so background-task wrapping via @rx.event(background=True) is rejected: resolve_upload_handler_param raises UploadTypeError before the handler is used. The check inspects handler.is_background on the resolved EventHandler.","triggerScenarios":"Decorating an upload handler with @rx.event(background=True) and passing it to rx.upload_file(handler=...). The validation happens while resolving the event spec, i.e. at component render/compile of the upload flow.","commonSituations":"Copying a background-task pattern onto file-upload handlers, attempting long-running upload processing with background=True on the upload endpoint itself.","solutions":["Remove background=True from the upload handler decoration","Do heavy post-upload processing in a separate background event handler triggered after the upload completes"],"exampleFix":"# before\n@rx.event(background=True)\nasync def handle_upload(files: list[rx.UploadFile]): ...\nrx.upload_file(handler=handle_upload)\n# after\n@rx.event\ndef handle_upload(files: list[rx.UploadFile]): ...\n\n@rx.event(background=True)\nasync def process_upload(): ...\n","handlingStrategy":"type-guard","validationCode":"assert not getattr(handler, \"is_background\", False), \"upload handlers must not be background events\"","typeGuard":"def is_plain_upload_handler(handler) -> bool:\n    return not getattr(handler, \"is_background\", False)","tryCatchPattern":"null","preventionTips":["Keep upload handlers synchronous wrt decoration; move heavy work to a follow-up background event","Code-review uploads for copied background=True decorators"],"tags":["upload","event-handler","background-task","validation"],"backgroundTag":"upload-handler-validation","analyzedSha":"45b8ed5ab735f8a56bbb09a42384f030eb0208e7","analyzedAt":"2026-08-28T19:25:27.644Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}