reflex-dev/reflex · error · HTTPException

Malformed upload event args.

Error message

Malformed upload event args.

What it means

The upload-event-args text field must be a JSON document; json.loads failing raises HTTPException 400 'Malformed upload event args.' chained from the JSONDecodeError. Empty input is allowed and decodes to {}.

Source

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

def _decode_event_args(encoded: str | None) -> dict[str, Any]:
    """Decode the extra bound handler args sent alongside an upload.

    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.

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Send the args field as a strict JSON object string, e.g. '{"arg1": 1}'
2. Verify the client isn't form-encoding the value; use JSON.stringify exactly once
3. Inspect the chained JSONDecodeError for the exact syntax offset

Example fix

# before
curl -F 'args=arg1=1&arg2=2' ...

# after
curl -F 'args={"arg1": 1, "arg2": 2}' ...

json.loads(args_str)  # raises locally if client-side payload is malformed

def is_json_args(s: str) -> bool:
    import json
    try:
        json.loads(s)
        return True
    except json.JSONDecodeError:
        return False

except json.JSONDecodeError as e:
    fix_payload(e.pos)  # validate before sending

When it happens

Trigger: The args form field contains invalid JSON (truncated payload, plain form text, encoding corruption) when the server decodes bound handler arguments.

Common situations: Custom clients sending URL-encoded or form-serialized values instead of JSON; truncated bodies from size limits; double-encoding (JSON string of a JSON string); tests posting arbitrary text in the args field.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Upload event args must be a JSON object.
• 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/634c5ed898db3bd2. Report an issue: GitHub.