alibaba/spring-ai-alibaba · error · BizException

INVALID_PARAMS

INVALID_PARAMS

Error message

{documents} placeholder is missing in instructions

What it means

KnowledgeBaseRetrievalAdvisor.before validates that the advisor's system prompt template contains the required {documents} placeholder using PromptAssert.templateHasRequiredPlaceholders; if not, it throws a BizException with ErrorCode.INVALID_PARAMS and message "{documents} placeholder is missing in instructions". The advisor needs the placeholder to inject retrieved knowledge-base documents into the prompt.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/rag/advisor/KnowledgeBaseRetrievalAdvisor.java:153

		// 3.1. Define prompt parameters.
		Map<String, Object> promptParameters = new HashMap<>();
		promptParameters.put(RagConstants.DOCUMENTS_PLACEHOLDER, documentContext);

		Map<String, Object> promptVariables = agentContext.getPromptVariables();
		LogUtils.info("query augment, prompt variables: {}", promptVariables);
		if (!CollectionUtils.isEmpty(promptVariables)) {
			promptParameters.putAll(promptVariables);
		}

		// 3.2. Augment user prompt with document context.
		SystemMessage templatedSystemMessage = chatClientRequest.prompt().getSystemMessage();

		PromptTemplate promptTemplate = new SystemPromptTemplate(templatedSystemMessage.getText());
		try {
			PromptAssert.templateHasRequiredPlaceholders(promptTemplate, RagConstants.DOCUMENTS_PLACEHOLDER);
		}
		catch (Exception e) {
			throw new BizException(
					ErrorCode.INVALID_PARAMS.toError("documents", "{documents} placeholder is missing in instructions"),
					e);
		}

		Message systemMessage = promptTemplate.createMessage(promptParameters);
		chatClientRequest.prompt()
			.getInstructions()
			.removeIf(element -> element.getMessageType() == MessageType.SYSTEM);
		chatClientRequest.prompt().getInstructions().add(0, systemMessage);

		// 4. Update advised request with augmented prompt.
		context.put(FILE_SEARCH_RESULT, documents);

		return chatClientRequest.mutate()
			.prompt(chatClientRequest.prompt().augmentUserMessage(request.getText()))
			.context(context)
			.build();
	}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Add {documents} back into the advisor instructions string where retrieved documents should be inserted.
2. If using a different templating syntax, convert it to Spring AI's {placeholder} style (single curly braces, StringTemplate-based).
3. Write a startup test asserting the configured instructions contain RagConstants.DOCUMENTS_PLACEHOLDER before the advisor is used.

Example fix

// before
String instructions = "Answer the user question using the knowledge base.";
// after
String instructions = "Answer the user question using the knowledge base:\n{documents}";

// Java
if (instructions == null || !instructions.contains("{documents}")) {
    throw new IllegalArgumentException("instructions must contain {documents} placeholder");
}

try {
    advisor.before(request, advisorContext);
} catch (BizException e) {
    if (e.getMessage().contains("placeholder is missing")) {
        // fix advisor instructions configuration
    }
}

When it happens

Trigger: Constructing KnowledgeBaseRetrievalAdvisor with custom instructions that omit the literal {documents} placeholder, then running a chat request that triggers the advisor's before() callback.

Common situations: Customizing the system prompt/instructions and accidentally removing the placeholder; copying a prompt template from another RAG library that uses a different variable syntax ({{documents}}, $documents); template stored in config and edited by hand.

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

• regex cannot be empty
• Elastic search index name must be provided
• INVALID_PARAMS
• Oauth2UserNotFound
• InvalidParameter

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