reflex-dev/reflex · error · HTTPException

Upload event args must be a JSON object.

Error message

Upload event args must be a JSON object.

What it means

After JSON parsing succeeds, the decoded args must be a JSON object (dict) because they map to handler keyword arguments. Arrays, strings, numbers, or null raise HTTPException 400 'Upload event args must be a JSON object.'

Source

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

    Args:
        encoded: The JSON-encoded args form field value, or ``None`` if absent.

    Returns:
        The decoded extra args, or an empty mapping if none were sent.

    Raises:
        HTTPException: If the value is present but not a valid JSON object.
    """
    if not encoded:
        return {}
    try:
        decoded = json.loads(encoded)
    except json.JSONDecodeError as exc:
        raise HTTPException(
            status_code=400, detail="Malformed upload event args."
        ) from exc
    if not isinstance(decoded, dict):
        raise HTTPException(
            status_code=400, detail="Upload event args must be a JSON object."
        )
    return decoded


def _buffered_upload_args(form_data: FormData) -> dict[str, Any]:
    """Decode the bound handler args from a buffered upload's form data.

    Args:
        form_data: The parsed multipart form data.

    Returns:
        The decoded extra args, or an empty mapping if none were sent.

    Raises:
        HTTPException: If the args field is a file or not a valid JSON object.
    """
    raw_args = form_data.get(UPLOAD_EVENT_ARGS_FIELD)

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Wrap the payload in an object with named keys matching the handler signature: {"arg1": ...}
2. Check that JSON.stringify is applied to an object, not an array/scalar
3. Align arg names with the upload handler's parameter names

Example fix

// before
args: JSON.stringify([1, 2])

// after
args: JSON.stringify({arg1: 1, arg2: 2})

assert isinstance(json.loads(args_str), dict)

def is_json_object(s: str) -> bool:
    import json
    return isinstance(json.loads(s), dict)

When it happens

Trigger: The args field decodes to valid JSON that is not an object: '[1,2]', '"text"', '123', 'null'.

Common situations: Clients sending a JSON array of positional args; stringified scalars; frameworks serializing the whole payload as an array.

Related errors

• Malformed upload event args.
• Missing reflex-client-token or reflex-event-handler header.
• @rx.event(background=True) is not supported for upload handl
• `{handler_name}` handler should have a parameter annotated a
• LiteralVar subclasses must implement the json method.

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