{"record":{"id":"94497ff050dc37aa","repo":"alibaba/spring-ai-alibaba","slug":"missing-params-94497f","errorCode":"MISSING_PARAMS","errorMessage":"category","messagePattern":"category","errorType":"error_code","errorClass":"BizException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/builder/controller/FileController.java","lineNumber":78,"sourceCode":"\t/** File manager for handling file operations */\n\tprivate final FileManager fileManager;\n\n\t/** Oss manager */\n\tprivate final OssManager ossManager;\n\n\t/**\n\t * Upload multiple files and return their upload policies\n\t * @param files Array of files to upload\n\t * @param category Category of the files\n\t * @return List of upload policies for the uploaded files\n\t */\n\t@PostMapping(value = \"upload\", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)\n\tpublic Result<List<UploadPolicy>> uploadDocument(@RequestPart(\"files\") MultipartFile[] files,\n\t\t\t@RequestPart(\"category\") String category) {\n\t\tRequestContext context = RequestContextHolder.getRequestContext();\n\n\t\tif (Objects.isNull(category)) {\n\t\t\tthrow new BizException(ErrorCode.MISSING_PARAMS.toError(\"category\"));\n\t\t}\n\n\t\tif (ArrayUtils.isEmpty(files)) {\n\t\t\tthrow new BizException(ErrorCode.MISSING_PARAMS.toError(\"files\"));\n\t\t}\n\n\t\tList<UploadPolicy> policies = new ArrayList<>();\n\t\tfor (MultipartFile file : files) {\n\t\t\tString path = fileManager.saveFile(file, category, context);\n\t\t\tString ext = FilenameUtils.getExtension(file.getOriginalFilename());\n\t\t\text = StringUtils.lowerCase(ext);\n\t\t\tUploadPolicy uploadPolicy = UploadPolicy.builder()\n\t\t\t\t.path(path)\n\t\t\t\t.name(file.getOriginalFilename())\n\t\t\t\t.extension(ext)\n\t\t\t\t.contentType(file.getContentType())\n\t\t\t\t.size(file.getSize())\n\t\t\t\t.build();","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/builder/controller/FileController.java#L60-L96","documentation":"The uploadDocument endpoint (POST upload, multipart/form-data) requires a 'category' form part alongside 'files'. When the category part is absent (null) the controller throws BizException(MISSING_PARAMS, \"category\"). The category determines the storage path via fileManager.saveFile.","triggerScenarios":"Multipart upload where the 'category' form field is omitted, e.g. appending only the file parts in FormData and forgetting the category entry, or @RequestPart(\"category\") not satisfied by the client.","commonSituations":"Frontend FormData construction missing the category key; API clients sending JSON instead of multipart form fields; category value accidentally named differently ('type', 'folder') so the part is missing.","solutions":["Include a 'category' text part in the multipart/form-data body alongside 'files'.","Verify the part name is exactly 'category' (case-sensitive).","Ensure the Content-Type is multipart/form-data and fields are sent as form parts, not JSON.","Default the category client-side (e.g. 'default') when the user hasn't chosen one."],"exampleFix":"// before\nconst fd = new FormData();\nfd.append('files', file);\nfetch('/files/upload', { method: 'POST', body: fd }); // category missing\n// after\nconst fd = new FormData();\nfd.append('files', file);\nfd.append('category', 'knowledge-base-doc');\nfetch('/files/upload', { method: 'POST', body: fd });","handlingStrategy":"validation","validationCode":"// JS caller\nif (!category) throw new Error('category is required for upload');\nconst fd = new FormData();\nfd.append('category', category);\nfor (const f of files) fd.append('files', f);\nfetch('/files/upload', { method: 'POST', body: fd });","typeGuard":"function canUpload(files, category) {\n  return Array.isArray(files) && files.length > 0 && typeof category === 'string' && category.length > 0;\n}","tryCatchPattern":"try {\n  await uploadFiles(files, category);\n} catch (e) {\n  if (e.code === 'MISSING_PARAMS') {\n    throw new Error('Upload rejected: ensure multipart parts \"files\" and \"category\" are present');\n  }\n  throw e;\n}","preventionTips":["Always append the exact part name 'category' to multipart FormData.","Send text fields as form parts, not JSON, when using multipart/form-data.","Provide a default category in the UI to avoid empty submissions."],"tags":["rest","multipart","validation","file-upload"],"backgroundTag":"missing-required-argument","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}