alibaba/spring-ai-alibaba · error · BizException

MISSING_PARAMS

MISSING_PARAMS

Error message

category

What it means

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.

Solutions

1. Include a 'category' text part in the multipart/form-data body alongside 'files'.
2. Verify the part name is exactly 'category' (case-sensitive).
3. Ensure the Content-Type is multipart/form-data and fields are sent as form parts, not JSON.
4. Default the category client-side (e.g. 'default') when the user hasn't chosen one.

Example fix

// before
const fd = new FormData();
fd.append('files', file);
fetch('/files/upload', { method: 'POST', body: fd }); // category missing
// after
const fd = new FormData();
fd.append('files', file);
fd.append('category', 'knowledge-base-doc');
fetch('/files/upload', { method: 'POST', body: fd });

// JS caller
if (!category) throw new Error('category is required for upload');
const fd = new FormData();
fd.append('category', category);
for (const f of files) fd.append('files', f);
fetch('/files/upload', { method: 'POST', body: fd });

function canUpload(files, category) {
  return Array.isArray(files) && files.length > 0 && typeof category === 'string' && category.length > 0;
}

try {
  await uploadFiles(files, category);
} catch (e) {
  if (e.code === 'MISSING_PARAMS') {
    throw new Error('Upload rejected: ensure multipart parts "files" and "category" are present');
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• graphName cannot be null or empty
• graphName cannot be null or empty
• AgentCard or AgentCardProvider must be provided
• AgentScope Model must be provided for AgentScope routing…
• AgentScope routing flow requires at least one sub-agent

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/94497ff050dc37aa. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/builder/controller/FileController.java:78

	/** File manager for handling file operations */
	private final FileManager fileManager;

	/** Oss manager */
	private final OssManager ossManager;

	/**
	 * Upload multiple files and return their upload policies
	 * @param files Array of files to upload
	 * @param category Category of the files
	 * @return List of upload policies for the uploaded files
	 */
	@PostMapping(value = "upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
	public Result<List<UploadPolicy>> uploadDocument(@RequestPart("files") MultipartFile[] files,
			@RequestPart("category") String category) {
		RequestContext context = RequestContextHolder.getRequestContext();

		if (Objects.isNull(category)) {
			throw new BizException(ErrorCode.MISSING_PARAMS.toError("category"));
		}

		if (ArrayUtils.isEmpty(files)) {
			throw new BizException(ErrorCode.MISSING_PARAMS.toError("files"));
		}

		List<UploadPolicy> policies = new ArrayList<>();
		for (MultipartFile file : files) {
			String path = fileManager.saveFile(file, category, context);
			String ext = FilenameUtils.getExtension(file.getOriginalFilename());
			ext = StringUtils.lowerCase(ext);
			UploadPolicy uploadPolicy = UploadPolicy.builder()
				.path(path)
				.name(file.getOriginalFilename())
				.extension(ext)
				.contentType(file.getContentType())
				.size(file.getSize())
				.build();

View on GitHub (pinned to f82da0b50f)