{"record":{"id":"c12c76a40f11f496","repo":"reflex-dev/reflex","slug":"event-handler-self-fn-name-argument-clash-r","errorCode":null,"errorMessage":"Event handler {self.fn.__name__} argument {clash!r} conflicts with a reserved upload argument.","messagePattern":"Event handler (.+?) argument (.+?) conflicts with a reserved upload argument\\.","errorType":"exception","errorClass":"EventHandlerTypeError","httpStatus":null,"severity":"error","filePath":"packages/reflex-base/src/reflex_base/event/__init__.py","lineNumber":685,"sourceCode":"            except TypeError as e:\n                msg = f\"Arguments to event handlers must be Vars or JSON-serializable. Got {arg} of type {type(arg)}.\"\n                raise EventHandlerTypeError(msg) from e\n\n        if upload_event_spec is not None:\n            if not payload:\n                return upload_event_spec\n            # The extra bound args share the flat payload with the synthetic\n            # upload args, so reject names that would clobber a reserved upload\n            # key (files, upload_id, extra_headers, ...).\n            payload_names = [name._js_expr for name, _ in payload]\n            reserved = {name._js_expr for name, _ in upload_event_spec.args}\n            clash = next((name for name in payload_names if name in reserved), None)\n            if clash is not None:\n                msg = (\n                    f\"Event handler {self.fn.__name__} argument {clash!r} conflicts \"\n                    \"with a reserved upload argument.\"\n                )\n                raise EventHandlerTypeError(msg)\n            # The client uploadFiles handler forwards exactly the args named here,\n            # so it never has to know the reserved upload keys.\n            return upload_event_spec.with_args((\n                *upload_event_spec.args,\n                *payload,\n                (\n                    Var(_js_expr=UPLOAD_EVENT_ARG_NAMES_KEY),\n                    LiteralVar.create(payload_names),\n                ),\n            ))\n\n        # Return the event spec.\n        return EventSpec(\n            handler=self, args=tuple(payload), event_actions=self.event_actions.copy()\n        )\n\n\n@dataclasses.dataclass(","sourceCodeStart":667,"sourceCodeEnd":703,"githubUrl":"https://github.com/reflex-dev/reflex/blob/45b8ed5ab735f8a56bbb09a42384f030eb0208e7/packages/reflex-base/src/reflex_base/event/__init__.py#L667-L703","documentation":"When an upload event spec is combined with extra bound arguments, the client upload handler forwards reserved argument names (the upload kwargs). A user argument sharing one of those names would silently clobber the upload payload, so it is rejected.","triggerScenarios":"Calling a handler that mixes rx.upload_files(...) with keyword arguments whose names collide with the reserved upload argument names used internally (e.g. files, upload_id-like reserved keys).","commonSituations":"Handlers that accept a parameter commonly named like upload internals (files, url, data) and also receive an upload spec plus that kwarg in the same call.","solutions":["Rename the colliding argument (and the handler parameter) to something unique like my_files or payload_files","Pass the value through state instead of as a bound event argument"],"exampleFix":"# before\nState.upload(rx.upload_files(State.h), files=selected_files)\n# after\nState.upload(rx.upload_files(State.h), my_files=selected_files)","handlingStrategy":"validation","validationCode":"# Avoid mixing upload specs with kwargs named like upload internals\nupload_call_args = {'files', 'file'}\nassert not (set(kwargs) & upload_call_args) or 'rename kwargs before calling with an upload spec'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefix user-supplied event kwargs with a unique namespace (my_, ctx_)"],"tags":["reflex","file-upload","argument-error","name-collision"],"backgroundTag":"reserved-name-collision","analyzedSha":"45b8ed5ab735f8a56bbb09a42384f030eb0208e7","analyzedAt":"2026-08-28T19:25:27.644Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}