reflex-dev/reflex · error · UploadTypeError

@rx.event(background=True) is not supported for upload handl

Error message

@rx.event(background=True) is not supported for upload handler `{handler_name}`.

What it means

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.

Source

Thrown at packages/reflex-base/src/reflex_base/event/__init__.py:345

    Returns:
        The parameter name and annotation for the upload file argument.

    Raises:
        UploadTypeError: If the handler is a background task.
        UploadValueError: If the handler does not accept ``list[rx.UploadFile]``.
    """
    from reflex_components_core.core._upload import UploadFile

    from reflex_base.utils.exceptions import UploadTypeError, UploadValueError

    handler_name = _handler_name(handler)
    if handler.is_background:
        msg = (
            f"@rx.event(background=True) is not supported for upload handler "
            f"`{handler_name}`."
        )
        raise UploadTypeError(msg)

    for name, annotation in handler._get_type_hints().items():
        if name == "return" or get_origin(annotation) is not list:
            continue
        args = get_args(annotation)
        if len(args) == 1 and typehint_issubclass(args[0], UploadFile):
            return name, annotation

    msg = (
        f"`{handler_name}` handler should have a parameter annotated as "
        "list[rx.UploadFile]"
    )
    raise UploadValueError(msg)


def resolve_upload_chunk_handler_param(handler: "EventHandler") -> tuple[str, type]:
    """Validate and resolve the UploadChunkIterator parameter for a handler.

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Remove background=True from the upload handler decoration
2. Do heavy post-upload processing in a separate background event handler triggered after the upload completes

Example fix

# before
@rx.event(background=True)
async def handle_upload(files: list[rx.UploadFile]): ...
rx.upload_file(handler=handle_upload)
# after
@rx.event
def handle_upload(files: list[rx.UploadFile]): ...

@rx.event(background=True)
async def process_upload(): ...

assert not getattr(handler, "is_background", False), "upload handlers must not be background events"

def is_plain_upload_handler(handler) -> bool:
    return not getattr(handler, "is_background", False)

null

When it happens

Trigger: 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.

Common situations: Copying a background-task pattern onto file-upload handlers, attempting long-running upload processing with background=True on the upload endpoint itself.

Related errors

• `{handler_name}` handler should have a parameter annotated a
• @rx.event(background=True) is required for upload_files_chun
• {on_upload_progress} is not a valid event handler.
• Var-returning `@rx.memo` `{func_name}` cannot depend on embe
• `rx.EventHandler` parameters are only supported on component

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/d88bef6119e735d1. Report an issue: GitHub.