reflex-dev/reflex · error · UploadTypeError

@rx.event(background=True) is required for upload_files_chun

Error message

@rx.event(background=True) is required for upload_files_chunk handler `{handler_name}`.

What it means

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.

Source

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

    Args:
        handler: The event handler to inspect.

    Returns:
        The parameter name and annotation for the iterator argument.

    Raises:
        UploadTypeError: If the handler is not a background task.
        UploadValueError: If the handler does not accept an UploadChunkIterator.
    """
    from reflex_components_core.core._upload import UploadChunkIterator

    from reflex_base.utils.exceptions import UploadTypeError, UploadValueError

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

    for name, annotation in handler._get_type_hints().items():
        if name == "return":
            continue
        if annotation is UploadChunkIterator:
            return name, annotation

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


@dataclasses.dataclass(
    init=True,
    frozen=True,
    kw_only=True,

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Decorate the handler with @rx.event(background=True)
2. Ensure the handler is a generator function that yields inside `async for chunk in upload_chunk_iterator`
3. Check that you are passing the undecorated-state method reference (State.upload_handler), not a partially applied or wrapped function

Example fix

# before
class State(rx.State):
    @rx.event
    async def handle(self, files: rx.UploadChunkIterator):
        async for chunk in files: ...
# after
class State(rx.State):
    @rx.event(background=True)
    async def handle(self, files: rx.UploadChunkIterator):
        async for chunk in files: ...

import inspect
from reflex_base.event import EventHandler

def is_background_upload_handler(h) -> bool:
    return isinstance(h, EventHandler) and h.is_background

def is_background_upload_handler(h) -> TypeGuard[EventHandler]: return isinstance(h, EventHandler) and h.is_background

When it happens

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

Common situations: 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.

Related errors

• `{handler_name}` handler should have a parameter annotated a
• Event handler {self.fn.__name__} received multiple file uplo
• {on_upload_progress} is not a valid event handler.
• `rx.EventHandler` parameters are only supported on component
• `children` in `{fn_name}` cannot be an `rx.EventHandler`; us

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