{"record":{"id":"262edd9bd52e60a1","repo":"reflex-dev/reflex","slug":"upload-event-args-must-be-a-text-field-not-a-file","errorCode":null,"errorMessage":"Upload event args must be a text field, not a file.","messagePattern":"Upload event args must be a text field, not a file\\.","errorType":"http","errorClass":"MultiPartException","httpStatus":null,"severity":"error","filePath":"packages/reflex-components-core/src/reflex_components_core/core/_upload.py","lineNumber":411,"sourceCode":"            msg = 'The Content-Disposition header field \"name\" must be provided.'\n            raise MultiPartException(msg) from err\n\n        if b\"filename\" not in options:\n            # Capture the bound-args field; ignore any other non-file field.\n            if field_name == UPLOAD_EVENT_ARGS_FIELD:\n                if self._seen_upload_chunk:\n                    # The handler is dispatched at the first file part, so a late\n                    # args field would be silently dropped; reject it loudly.\n                    msg = \"Upload event args must precede the file parts.\"\n                    raise MultiPartException(msg)\n                self._current_part.is_text_field = True\n                self._args_buffer = bytearray()\n            return\n        if field_name == UPLOAD_EVENT_ARGS_FIELD:\n            # A file under the args field name would otherwise be pushed as a\n            # phantom file upload; reject it instead of silently dropping it.\n            msg = \"Upload event args must be a text field, not a file.\"\n            raise MultiPartException(msg)\n        filename = _sanitize_upload_filename(\n            _user_safe_decode(options[b\"filename\"], self._charset)\n        )\n\n        content_type = \"\"\n        for header_name, header_value in self._current_part.item_headers:\n            if header_name == b\"content-type\":\n                content_type = _user_safe_decode(header_value, self._charset)\n                break\n\n        self._current_part.field_name = field_name\n        self._current_part.filename = filename\n        self._current_part.content_type = content_type\n        self._current_part.offset = 0\n        self._current_part.bytes_emitted = 0\n        self._current_part.is_upload_chunk = True\n        # The args field precedes the files, so by the first file part the bound\n        # args are fully parsed and the handler can be dispatched.","sourceCodeStart":393,"sourceCodeEnd":429,"githubUrl":"https://github.com/reflex-dev/reflex/blob/45b8ed5ab735f8a56bbb09a42384f030eb0208e7/packages/reflex-components-core/src/reflex_components_core/core/_upload.py#L393-L429","documentation":"If a part carries the upload-event-args field name but also has a filename (i.e. it is a file part), the parser rejects it: the args channel must be a plain text field. Otherwise the file would be pushed as a phantom upload or corrupt args decoding.","triggerScenarios":"Content-Disposition: form-data; name=\"<args-field>\"; filename=\"x.json\" — a file uploaded under the reserved args field name.","commonSituations":"Custom clients naming their file field identically to Reflex's internal args field name; name collisions when the user picks a field name clashing with the reserved one; fuzzing/malformed requests.","solutions":["Rename your file form field so it doesn't collide with the reserved args field name (use the conventional 'files')","Send args as a plain text field without a filename attribute","Use the standard Reflex upload client which never sends files under the args name"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"assert all(p.filename is None for p in parts if p.name == ARGS_FIELD)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never reuse the reserved args field name for files","Send args strictly as a text field"],"tags":["upload","multipart","field-validation"],"backgroundTag":"multipart-validation-failed","analyzedSha":"45b8ed5ab735f8a56bbb09a42384f030eb0208e7","analyzedAt":"2026-08-28T19:25:27.644Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}