{"record":{"id":"cdb380b46327e264","repo":"reflex-dev/reflex","slug":"handler-name-handler-should-have-a-parameter-a","errorCode":null,"errorMessage":"`{handler_name}` handler should have a parameter annotated as list[rx.UploadFile]","messagePattern":"`(.+?)` handler should have a parameter annotated as list\\[rx\\.UploadFile\\]","errorType":"exception","errorClass":"UploadValueError","httpStatus":null,"severity":"error","filePath":"packages/reflex-base/src/reflex_base/event/__init__.py","lineNumber":358,"sourceCode":"    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\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","sourceCodeStart":340,"sourceCodeEnd":376,"githubUrl":"https://github.com/reflex-dev/reflex/blob/45b8ed5ab735f8a56bbb09a42384f030eb0208e7/packages/reflex-base/src/reflex_base/event/__init__.py#L340-L376","documentation":"resolve_upload_handler_param scans the handler's type hints for exactly one parameter annotated list[rx.UploadFile] (origin list, single arg subclassing UploadFile). If no parameter matches, UploadValueError is raised telling you the required annotation. Other list[...] params and non-list annotations are skipped.","triggerScenarios":"Defining an upload handler whose parameter is annotated rx.UploadFile (not a list), list[UploadFile]-equivalents from a different class, list[Any], or missing the parameter entirely — then using it with rx.upload_file().","commonSituations":"Annotating with a single UploadFile because the UI uploads one file, importing UploadFile from the wrong module so the subclass check fails, or renaming/loosening the annotation.","solutions":["Annotate exactly one parameter as list[rx.UploadFile] even for single-file uploads","Import UploadFile from reflex so the issubclass check passes","Keep the parameter positional and don't wrap it in extra generics"],"exampleFix":"# before\n@rx.event\ndef handle_upload(file: rx.UploadFile): ...\n# after\n@rx.event\ndef handle_upload(files: list[rx.UploadFile]): ...\n","handlingStrategy":"type-guard","validationCode":"import typing\nfrom reflex import UploadFile\nhints = typing.get_type_hints(handler.fn)\nassert any(get_origin(a) is list and get_args(a) and issubclass(get_args(a)[0], UploadFile)\n           for n, a in hints.items() if n != \"return\"), \"missing list[rx.UploadFile] param\"","typeGuard":"def has_upload_param(handler) -> bool:\n    import typing\n    from reflex import UploadFile\n    for n, a in typing.get_type_hints(handler.fn).items():\n        if n == \"return\":\n            continue\n        if typing.get_origin(a) is list and (args := typing.get_args(a)) and issubclass(args[0], UploadFile):\n            return True\n    return False","tryCatchPattern":"null","preventionTips":["Standardize the annotation list[rx.UploadFile] even for single files","Import UploadFile from reflex, not FastAPI/starlette, so the subclass check matches"],"tags":["upload","type-annotation","event-handler","validation"],"backgroundTag":"upload-handler-validation","analyzedSha":"45b8ed5ab735f8a56bbb09a42384f030eb0208e7","analyzedAt":"2026-08-28T19:25:27.644Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}