alibaba/spring-ai-alibaba · warning · BizException

MISSING_PARAMS

MISSING_PARAMS

Error message

kbId

What it means

BizException(ErrorCode.MISSING_PARAMS.toError("kbId")) is thrown by DocumentController.createDocuments (POST /{kbId}/documents) when the kbId path variable is null. The knowledge-base id is required so the uploaded files are attached to the right KB; the controller rejects a null id before validating the rest of the request. Normally the route guarantees the value, so a null indicates direct invocation.

Source

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

	private final DocumentService documentService;

	public DocumentController(DocumentService documentService) {
		this.documentService = documentService;
	}

	/**
	 * Creates new documents in the knowledge base
	 * @param kbId Knowledge base ID
	 * @param request Document creation request
	 * @return Created document IDs
	 */
	@PostMapping(value = "/{kbId}/documents")
	public Result<List<String>> createDocuments(@PathVariable("kbId") String kbId,
			@RequestBody CreateDocumentRequest request) {
		RequestContext context = RequestContextHolder.getRequestContext();

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

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

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

		request.setKbId(kbId);
		List<String> docIds = documentService.createDocuments(request);
		return Result.success(context.getRequestId(), docIds);
	}

	/**
	 * Updates an existing document
	 * @param kbId Knowledge base ID

View on GitHub (pinned to f82da0b50f)

Solutions

1. POST the documents to a concrete knowledge base path, e.g. POST /{kbId}/documents with kbId filled in
2. In direct calls, pass the real kbId string instead of null
3. Catch BizException MISSING_PARAMS and ask the caller for a valid knowledge-base id

Example fix

// before
controller.createDocuments(null, createRequest);
// after
controller.createDocuments("kb-123", createRequest);

if (kbId == null || kbId.isBlank()) {
  throw new IllegalArgumentException('kbId is required in the URL path to create documents');
}

function hasKbId(route) {
  return typeof route.kbId === 'string' && route.kbId.trim().length > 0;
}

try {
  return documentApi.createDocuments(kbId, request);
} catch (BizException e) {
  if ("MISSING_PARAMS".equals(e.getCode())) {
    throw new ClientValidationError("kbId path variable is required: " + e.getMessage());
  }
  throw e;
}

When it happens

Trigger: Invoking the create-documents handler with a null kbId argument — via direct method call in tests or programmatic invocation; the HTTP route itself always contains the path segment.

Common situations: Controller unit tests with null path variables; reflection-based callers; generated client stubs that fail to substitute the kbId placeholder.

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

• MISSING_PARAMS
• MISSING_PARAMS
• MISSING_PARAMS
• MISSING_PARAMS
• MISSING_PARAMS

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