{"record":{"id":"1099c79466f46ef7","repo":"reflex-dev/reflex","slug":"handler-name-handler-should-have-a-parameter-a-1099c7","errorCode":null,"errorMessage":"`{handler_name}` handler should have a parameter annotated as rx.UploadChunkIterator","messagePattern":"`(.+?)` handler should have a parameter annotated as rx\\.UploadChunkIterator","errorType":"exception","errorClass":"UploadValueError","httpStatus":null,"severity":"error","filePath":"packages/reflex-base/src/reflex_base/event/__init__.py","lineNumber":393,"sourceCode":"\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,\n)\nclass EventActionsMixin:\n    \"\"\"Mixin for DOM event actions.\n\n    Attributes:\n        event_actions: Whether to `preventDefault` or `stopPropagation` on the event.\n    \"\"\"\n\n    event_actions: dict[str, bool | int] = dataclasses.field(default_factory=dict)\n\n    @property\n    def stop_propagation(self) -> Self:","sourceCodeStart":375,"sourceCodeEnd":411,"githubUrl":"https://github.com/reflex-dev/reflex/blob/45b8ed5ab735f8a56bbb09a42384f030eb0208e7/packages/reflex-base/src/reflex_base/event/__init__.py#L375-L411","documentation":"A handler registered for chunked file uploads must declare exactly one parameter annotated as rx.UploadChunkIterator so the framework knows where to inject the chunk stream. Without it there is no way to deliver uploaded chunks to your code.","triggerScenarios":"Calling upload_files_chunk (or upload_file) with a background=True handler whose parameters use other annotations (e.g. list[UploadFile], bytes, or no annotation) and none is rx.UploadChunkIterator.","commonSituations":"Porting an old rx.upload(_files) handler that took list[rx.UploadFile] to the chunked API, or forgetting to annotate the new parameter when adding the handler.","solutions":["Add a parameter annotated rx.UploadChunkIterator to the handler, e.g. `async def h(self, files: rx.UploadChunkIterator)`","Import/qualify the annotation exactly as rx.UploadChunkIterator (string annotations must resolve to it)","Keep @rx.event(background=True) on the handler as well, otherwise error 80 fires first"],"exampleFix":"# before\n@rx.event(background=True)\nasync def handle(self, files: list[rx.UploadFile]): ...\n# after\n@rx.event(background=True)\nasync def handle(self, files: rx.UploadChunkIterator):\n    async for chunk in files: ...","handlingStrategy":"type-guard","validationCode":"import typing\nfrom reflex import UploadChunkIterator\n\ndef has_chunk_iterator_param(fn) -> bool:\n    hints = typing.get_type_hints(fn)\n    return any(h is UploadChunkIterator for k, h in hints.items() if k != 'return')","typeGuard":"def has_chunk_iterator_param(fn) -> TypeGuard[Callable]: return any(h is UploadChunkIterator for h in typing.get_type_hints(fn).values() if h is not type(None))","tryCatchPattern":null,"preventionTips":["Standardize the parameter name and annotation files: rx.UploadChunkIterator on all upload handlers","Add a unit test asserting the handler signature resolves"],"tags":["reflex","file-upload","type-annotation","event-handler"],"backgroundTag":"missing-type-annotation","analyzedSha":"45b8ed5ab735f8a56bbb09a42384f030eb0208e7","analyzedAt":"2026-08-28T19:25:27.644Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}