alibaba/spring-ai-alibaba · error · BizException

MISSING_PARAMS

MISSING_PARAMS

Error message

docId

What it means

POST /{docId}/chunks (create document chunk) requires the docId path variable, and the controller throws BizException with ErrorCode.MISSING_PARAMS when it is null. Since docId is a path variable, Spring binds it from the URL; a null here means the request hit an unintended route mapping or was built without the path segment.

Source

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

	/** Service for handling document operations */
	private final DocumentService documentService;

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

	/**
	 * Creates a new document chunk
	 * @param docId Document ID
	 * @param chunk Chunk data
	 * @return Created chunk ID
	 */
	@PostMapping(value = "/{docId}/chunks")
	public Result<String> createDocumentChunk(@PathVariable("docId") String docId, @RequestBody DocumentChunk chunk) {
		RequestContext context = RequestContextHolder.getRequestContext();

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

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

		chunk.setDocId(docId);
		String chunkId = documentService.createDocumentChunk(chunk);
		return Result.success(context.getRequestId(), chunkId);
	}

	/**
	 * Updates an existing document chunk
	 * @param docId Document ID
	 * @param chunkId Chunk ID
	 * @param chunk Updated chunk data
	 */
	@PutMapping("/{docId}/chunks/{chunkId}")

View on GitHub (pinned to f82da0b50f)

Solutions

1. Interpolate a real document id into the URL path segment, e.g. /documents/{docId}/chunks.
2. Check client URL-building code for an unexpanded "${docId}"-style placeholder.
3. Verify no gateway rewrite removes the docId path segment.

Example fix

// before
const url = `/documents/${docId}/chunks`.replace('${docId}', '')
// after
if (!docId) throw new Error('docId required');
const url = `/documents/${docId}/chunks`;

if (docId) { fetch(`/documents/${docId}/chunks`, {method:'POST', body: JSON.stringify(chunk)}); }

const hasDocId = (id) => typeof id === 'string' && id.length > 0;

try { await createChunk(docId, chunk); } catch (e) { if (e.code === 'MISSING_PARAMS' && e.message === 'docId') { alert('Select a document first'); } else { throw e; } }

When it happens

Trigger: A request to the chunks creation endpoint whose URL lacks a concrete {docId} segment (e.g. a templated URL like "/documents//chunks" or "/documents/{docId}/chunks" never interpolated), yielding docId == null.

Common situations: URL template not interpolated in client code; empty string path segment; proxy/gateway stripping the segment; calling the endpoint via a hardcoded template string.

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/bd9c9558323d19ea. Report an issue: GitHub.