reflex-dev/reflex · error · MultiPartException

Upload event args must precede the file parts.

Error message

Upload event args must precede the file parts.

What it means

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.

Source

Thrown at packages/reflex-components-core/src/reflex_components_core/core/_upload.py:403

        )
        if disposition != b"form-data":
            msg = "Invalid upload chunk disposition."
            raise MultiPartException(msg)

        try:
            field_name = _user_safe_decode(options[b"name"], self._charset)
        except KeyError as err:
            msg = 'The Content-Disposition header field "name" must be provided.'
            raise MultiPartException(msg) from err

        if b"filename" not in options:
            # Capture the bound-args field; ignore any other non-file field.
            if field_name == UPLOAD_EVENT_ARGS_FIELD:
                if self._seen_upload_chunk:
                    # The handler is dispatched at the first file part, so a late
                    # args field would be silently dropped; reject it loudly.
                    msg = "Upload event args must precede the file parts."
                    raise MultiPartException(msg)
                self._current_part.is_text_field = True
                self._args_buffer = bytearray()
            return
        if field_name == UPLOAD_EVENT_ARGS_FIELD:
            # A file under the args field name would otherwise be pushed as a
            # phantom file upload; reject it instead of silently dropping it.
            msg = "Upload event args must be a text field, not a file."
            raise MultiPartException(msg)
        filename = _sanitize_upload_filename(
            _user_safe_decode(options[b"filename"], self._charset)
        )

        content_type = ""
        for header_name, header_value in self._current_part.item_headers:
            if header_name == b"content-type":
                content_type = _user_safe_decode(header_value, self._charset)
                break

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Append the args field before any file fields when constructing multipart bodies
2. Use the built-in Reflex upload flow (rx.upload component) which orders fields correctly
3. When testing with curl -F, place -F args=... before -F files=@...

Example fix

# before
curl -F files=@a.txt -F args='{}' ...

# after
curl -F args='{}' -F files=@a.txt ...

fd = FormData()
fd.append("args", json.dumps(args))  # BEFORE files
for f in files:
    fd.append("files", f, f.name)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Upload event args field is too large.
• Invalid upload chunk disposition.
• The Content-Disposition header field "name" must be provided
• Upload event args must be a text field, not a file.
• Missing boundary in multipart.

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/17175f496dcee487. Report an issue: GitHub.