{"record":{"id":"eb0dd51898323541","repo":"reflex-dev/reflex","slug":"rx-event-background-true-is-required-for-upload","errorCode":null,"errorMessage":"@rx.event(background=True) is required for upload_files_chunk handler `{handler_name}`.","messagePattern":"@rx\\.event\\(background=True\\) is required for upload_files_chunk handler `(.+?)`\\.","errorType":"exception","errorClass":"UploadTypeError","httpStatus":null,"severity":"error","filePath":"packages/reflex-base/src/reflex_base/event/__init__.py","lineNumber":381,"sourceCode":"\n    Args:\n        handler: The event handler to inspect.\n\n    Returns:\n        The parameter name and annotation for the iterator argument.\n\n    Raises:\n        UploadTypeError: If the handler is not a background task.\n        UploadValueError: If the handler does not accept an UploadChunkIterator.\n    \"\"\"\n    from reflex_components_core.core._upload import UploadChunkIterator\n\n    from reflex_base.utils.exceptions import UploadTypeError, UploadValueError\n\n    handler_name = _handler_name(handler)\n    if not handler.is_background:\n        msg = f\"@rx.event(background=True) is required for upload_files_chunk handler `{handler_name}`.\"\n        raise UploadTypeError(msg)\n\n    for name, annotation in handler._get_type_hints().items():\n        if name == \"return\":\n            continue\n        if annotation is UploadChunkIterator:\n            return name, annotation\n\n    msg = (\n        f\"`{handler_name}` handler should have a parameter annotated as \"\n        \"rx.UploadChunkIterator\"\n    )\n    raise UploadValueError(msg)\n\n\n@dataclasses.dataclass(\n    init=True,\n    frozen=True,\n    kw_only=True,","sourceCodeStart":363,"sourceCodeEnd":399,"githubUrl":"https://github.com/reflex-dev/reflex/blob/45b8ed5ab735f8a56bbb09a42384f030eb0208e7/packages/reflex-base/src/reflex_base/event/__init__.py#L363-L399","documentation":"Raised when a file-upload chunk handler passed to rx.upload_files_chunk (or the upload_file machinery) is not decorated with @rx.event(background=True). Chunked uploads stream many chunks over time, so the handler must run as a background task to avoid blocking the event loop.","triggerScenarios":"Passing a state method to upload_files_chunk (or on_upload_progress-style upload APIs that call resolve_upload_chunk_handler_param) where the method is decorated with plain @rx.event, @rx.event(background=False), or has no decorator at all.","commonSituations":"Migrating from the legacy upload API to chunked uploads, or writing a progress-tracking upload handler and forgetting that chunk iteration must be yielded from a background task.","solutions":["Decorate the handler with @rx.event(background=True)","Ensure the handler is a generator function that yields inside `async for chunk in upload_chunk_iterator`","Check that you are passing the undecorated-state method reference (State.upload_handler), not a partially applied or wrapped function"],"exampleFix":"# before\nclass State(rx.State):\n    @rx.event\n    async def handle(self, files: rx.UploadChunkIterator):\n        async for chunk in files: ...\n# after\nclass State(rx.State):\n    @rx.event(background=True)\n    async def handle(self, files: rx.UploadChunkIterator):\n        async for chunk in files: ...","handlingStrategy":"validation","validationCode":"import inspect\nfrom reflex_base.event import EventHandler\n\ndef is_background_upload_handler(h) -> bool:\n    return isinstance(h, EventHandler) and h.is_background","typeGuard":"def is_background_upload_handler(h) -> TypeGuard[EventHandler]: return isinstance(h, EventHandler) and h.is_background","tryCatchPattern":null,"preventionTips":["Always decorate chunked upload handlers with @rx.event(background=True) from the start","Copy a working upload_files_chunk example when adding new upload features"],"tags":["reflex","file-upload","event-handler","background-task"],"backgroundTag":"event-handler-validation-failed","analyzedSha":"45b8ed5ab735f8a56bbb09a42384f030eb0208e7","analyzedAt":"2026-08-28T19:25:27.644Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}