reflex-dev/reflex · error · MultiPartException

Upload event args field is too large.

Error message

Upload event args field is too large.

What it means

Streaming uploads encode the event handler's bound arguments as a single text field in the multipart body, capped at MAX_UPLOAD_EVENT_ARGS_BYTES to prevent unbounded memory use. Exceeding the cap while accumulating part data raises MultiPartException, aborting the request.

Source

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

    _extra_args_raw: str | None = None
    _started: bool = False
    _seen_upload_chunk: bool = False
    _part_count: int = 0
    _emitted_chunk_count: int = 0
    _emitted_bytes: int = 0
    _stream_chunk_count: int = 0

    def on_part_begin(self) -> None:
        """Reset parser state for a new multipart part."""
        self._current_part = _UploadChunkPart()

    def on_part_data(self, data: bytes, start: int, end: int) -> None:
        """Record streamed chunk data for the current part."""
        if self._current_part.is_text_field:
            self._args_buffer += data[start:end]
            if len(self._args_buffer) > MAX_UPLOAD_EVENT_ARGS_BYTES:
                msg = "Upload event args field is too large."
                raise MultiPartException(msg)
            return
        if (
            not self._current_part.is_upload_chunk
            or self._current_part.filename is None
        ):
            return

        message_bytes = data[start:end]
        self._chunks_to_emit.append(
            UploadChunk(
                filename=self._current_part.filename,
                offset=self._current_part.offset + self._current_part.bytes_emitted,
                content_type=self._current_part.content_type,
                data=message_bytes,
            )
        )
        self._current_part.bytes_emitted += len(message_bytes)
        self._emitted_chunk_count += 1

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Move large data out of the handler args — pass an ID/reference and fetch the data in state
2. Trim the bound arguments passed to the upload event handler
3. Configure/review MAX_UPLOAD_EVENT_ARGS_BYTES if you genuinely need bigger args

Example fix

// before
rx.upload(..., on_upload=State.handle_upload(State.big_json))

// after
rx.upload(..., on_upload=State.handle_upload())  # read big data from state

import json
assert len(json.dumps(bound_args)) < MAX_UPLOAD_EVENT_ARGS_BYTES

When it happens

Trigger: A multipart form field named as the upload event-args field whose accumulated data exceeds MAX_UPLOAD_EVENT_ARGS_BYTES, parsed by the streaming upload parser.

Common situations: Passing very large state values (huge strings/JSON blobs) as bound args to an upload handler: rx.upload_files(State.big_payload); or a malicious/oversized request body.

Related errors

• Invalid upload chunk disposition.
• 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/4ed30c0b58eaa92a. Report an issue: GitHub.