{"record":{"id":"17175f496dcee487","repo":"reflex-dev/reflex","slug":"upload-event-args-must-precede-the-file-parts","errorCode":null,"errorMessage":"Upload event args must precede the file parts.","messagePattern":"Upload event args must precede the file parts\\.","errorType":"exception","errorClass":"MultiPartException","httpStatus":null,"severity":"error","filePath":"packages/reflex-components-core/src/reflex_components_core/core/_upload.py","lineNumber":403,"sourceCode":"        )\n        if disposition != b\"form-data\":\n            msg = \"Invalid upload chunk disposition.\"\n            raise MultiPartException(msg)\n\n        try:\n            field_name = _user_safe_decode(options[b\"name\"], self._charset)\n        except KeyError as err:\n            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","sourceCodeStart":385,"sourceCodeEnd":421,"githubUrl":"https://github.com/reflex-dev/reflex/blob/45b8ed5ab735f8a56bbb09a42384f030eb0208e7/packages/reflex-components-core/src/reflex_components_core/core/_upload.py#L385-L421","documentation":"Streaming uploads dispatch the handler at the first file part, so the special args field (which carries the bound event arguments) must appear before any file parts. A late args field would be silently dropped, so Reflex rejects it loudly with MultiPartException.","triggerScenarios":"A multipart body where the upload-event-args text field appears after a file part — usually from custom clients that append fields after files, or reordered bodies.","commonSituations":"Manually built FormData where files are appended before the args field; custom non-browser upload clients with nonstandard field ordering; modified Reflex JS client from an older version.","solutions":["Append the args field before any file fields when constructing multipart bodies","Use the built-in Reflex upload flow (rx.upload component) which orders fields correctly","When testing with curl -F, place -F args=... before -F files=@..."],"exampleFix":"# before\ncurl -F files=@a.txt -F args='{}' ...\n\n# after\ncurl -F args='{}' -F files=@a.txt ...","handlingStrategy":"validation","validationCode":"fd = FormData()\nfd.append(\"args\", json.dumps(args))  # BEFORE files\nfor f in files:\n    fd.append(\"files\", f, f.name)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Append args/text fields before file fields","Rely on the built-in rx.upload client for correct ordering"],"tags":["upload","multipart","field-ordering"],"backgroundTag":"multipart-validation-failed","analyzedSha":"45b8ed5ab735f8a56bbb09a42384f030eb0208e7","analyzedAt":"2026-08-28T19:25:27.644Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}