reflex-dev/reflex · error · MultiPartException

Invalid upload chunk disposition.

Error message

Invalid upload chunk disposition.

What it means

Each multipart part in a streaming upload must use Content-Disposition: form-data. The Reflex parser rejects other dispositions (attachment, inline, etc.) with MultiPartException because it can only process form fields and file parts.

Source

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

        """Store the completed multipart header."""
        field = self._current_partial_header_name.lower()
        if field == b"content-disposition":
            self._current_part.content_disposition = self._current_partial_header_value
        self._current_part.item_headers.append((
            field,
            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

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Send parts with standard Content-Disposition: form-data; name="..." headers
2. Use a real FormData object in the browser or curl -F so dispositions are correct
3. Check for proxy/middleware that rewrites multipart headers

disposition, _ = parse_options_header(part_header)
assert disposition == b"form-data"

When it happens

Trigger: A client (curl -F, custom fetch, or non-browser tool) sends a part with Content-Disposition: attachment or inline instead of form-data in a streaming upload request.

Common situations: Custom upload scripts/tools that set nonstandard dispositions; proxies or middlewares rewriting multipart headers; hand-rolled multipart bodies in tests.

Related errors

• Upload event args field is too large.
• The Content-Disposition header field "name" must be provided
• 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/aec35b3e39d5672f. Report an issue: GitHub.