reflex-dev/reflex · error · MultiPartException

The Content-Disposition header field "name" must be provided

Error message

The Content-Disposition header field "name" must be provided.

What it means

Every multipart part must carry a name option in its Content-Disposition header so the parser can identify fields. A missing options[b"name"] raises MultiPartException chained from the KeyError.

Source

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

            self._current_partial_header_value,
        ))
        self._current_partial_header_name = b""
        self._current_partial_header_value = b""

    def on_headers_finished(self) -> None:
        """Parse upload metadata from multipart headers."""
        disposition, options = parse_options_header(
            self._current_part.content_disposition
        )
        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(

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Always include name= in each part: Content-Disposition: form-data; name="files"; filename="a.txt"
2. Use standard multipart libraries (requests files=, browser FormData) which always emit name
3. Validate/repair multipart construction in custom upload clients

assert b"name" in options, "each part needs a name"

When it happens

Trigger: A part whose header is `Content-Disposition: form-data` without `; name="field"`, typically from hand-crafted multipart bodies or buggy HTTP clients.

Common situations: Manually assembled multipart bodies in tests or scripts; malformed bodies from load balancers; clients that omit name for file-only parts (invalid per RFC 7578).

Related errors

• Upload event args field is too large.
• Invalid upload chunk disposition.
• Upload event args must precede the file parts.
• 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/2d000b027b2bd31f. Report an issue: GitHub.