{"record":{"id":"dd2dfa063c255b02","repo":"reflex-dev/reflex","slug":"upload-event-args-must-be-a-json-object","errorCode":null,"errorMessage":"Upload event args must be a JSON object.","messagePattern":"Upload event args must be a JSON object\\.","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/reflex-components-core/src/reflex_components_core/core/_upload.py","lineNumber":555,"sourceCode":"    Args:\n        encoded: The JSON-encoded args form field value, or ``None`` if absent.\n\n    Returns:\n        The decoded extra args, or an empty mapping if none were sent.\n\n    Raises:\n        HTTPException: If the value is present but not a valid JSON object.\n    \"\"\"\n    if not encoded:\n        return {}\n    try:\n        decoded = json.loads(encoded)\n    except json.JSONDecodeError as exc:\n        raise HTTPException(\n            status_code=400, detail=\"Malformed upload event args.\"\n        ) from exc\n    if not isinstance(decoded, dict):\n        raise HTTPException(\n            status_code=400, detail=\"Upload event args must be a JSON object.\"\n        )\n    return decoded\n\n\ndef _buffered_upload_args(form_data: FormData) -> dict[str, Any]:\n    \"\"\"Decode the bound handler args from a buffered upload's form data.\n\n    Args:\n        form_data: The parsed multipart form data.\n\n    Returns:\n        The decoded extra args, or an empty mapping if none were sent.\n\n    Raises:\n        HTTPException: If the args field is a file or not a valid JSON object.\n    \"\"\"\n    raw_args = form_data.get(UPLOAD_EVENT_ARGS_FIELD)","sourceCodeStart":537,"sourceCodeEnd":573,"githubUrl":"https://github.com/reflex-dev/reflex/blob/45b8ed5ab735f8a56bbb09a42384f030eb0208e7/packages/reflex-components-core/src/reflex_components_core/core/_upload.py#L537-L573","documentation":"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.'","triggerScenarios":"The args field decodes to valid JSON that is not an object: '[1,2]', '\"text\"', '123', 'null'.","commonSituations":"Clients sending a JSON array of positional args; stringified scalars; frameworks serializing the whole payload as an array.","solutions":["Wrap the payload in an object with named keys matching the handler signature: {\"arg1\": ...}","Check that JSON.stringify is applied to an object, not an array/scalar","Align arg names with the upload handler's parameter names"],"exampleFix":"// before\nargs: JSON.stringify([1, 2])\n\n// after\nargs: JSON.stringify({arg1: 1, arg2: 2})","handlingStrategy":"type-guard","validationCode":"assert isinstance(json.loads(args_str), dict)","typeGuard":"def is_json_object(s: str) -> bool:\n    import json\n    return isinstance(json.loads(s), dict)","tryCatchPattern":null,"preventionTips":["Use named keys matching handler parameters","Wrap arrays/scalars in an object before sending"],"tags":["upload","json","http-400"],"backgroundTag":"invalid-json-payload","analyzedSha":"45b8ed5ab735f8a56bbb09a42384f030eb0208e7","analyzedAt":"2026-08-28T19:25:27.644Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}