{"record":{"id":"19756e6d4a956919","repo":"alibaba/spring-ai-alibaba","slug":"invalid-params-19756e","errorCode":"INVALID_PARAMS","errorMessage":"{documents} placeholder is missing in instructions","messagePattern":"(.+?) placeholder is missing in instructions","errorType":"error_code","errorClass":"BizException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/rag/advisor/KnowledgeBaseRetrievalAdvisor.java","lineNumber":153,"sourceCode":"\t\t// 3.1. Define prompt parameters.\n\t\tMap<String, Object> promptParameters = new HashMap<>();\n\t\tpromptParameters.put(RagConstants.DOCUMENTS_PLACEHOLDER, documentContext);\n\n\t\tMap<String, Object> promptVariables = agentContext.getPromptVariables();\n\t\tLogUtils.info(\"query augment, prompt variables: {}\", promptVariables);\n\t\tif (!CollectionUtils.isEmpty(promptVariables)) {\n\t\t\tpromptParameters.putAll(promptVariables);\n\t\t}\n\n\t\t// 3.2. Augment user prompt with document context.\n\t\tSystemMessage templatedSystemMessage = chatClientRequest.prompt().getSystemMessage();\n\n\t\tPromptTemplate promptTemplate = new SystemPromptTemplate(templatedSystemMessage.getText());\n\t\ttry {\n\t\t\tPromptAssert.templateHasRequiredPlaceholders(promptTemplate, RagConstants.DOCUMENTS_PLACEHOLDER);\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new BizException(\n\t\t\t\t\tErrorCode.INVALID_PARAMS.toError(\"documents\", \"{documents} placeholder is missing in instructions\"),\n\t\t\t\t\te);\n\t\t}\n\n\t\tMessage systemMessage = promptTemplate.createMessage(promptParameters);\n\t\tchatClientRequest.prompt()\n\t\t\t.getInstructions()\n\t\t\t.removeIf(element -> element.getMessageType() == MessageType.SYSTEM);\n\t\tchatClientRequest.prompt().getInstructions().add(0, systemMessage);\n\n\t\t// 4. Update advised request with augmented prompt.\n\t\tcontext.put(FILE_SEARCH_RESULT, documents);\n\n\t\treturn chatClientRequest.mutate()\n\t\t\t.prompt(chatClientRequest.prompt().augmentUserMessage(request.getText()))\n\t\t\t.context(context)\n\t\t\t.build();\n\t}","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-core/src/main/java/com/alibaba/cloud/ai/studio/core/rag/advisor/KnowledgeBaseRetrievalAdvisor.java#L135-L171","documentation":"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.","triggerScenarios":"Constructing KnowledgeBaseRetrievalAdvisor with custom instructions that omit the literal {documents} placeholder, then running a chat request that triggers the advisor's before() callback.","commonSituations":"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.","solutions":["Add {documents} back into the advisor instructions string where retrieved documents should be inserted.","If using a different templating syntax, convert it to Spring AI's {placeholder} style (single curly braces, StringTemplate-based).","Write a startup test asserting the configured instructions contain RagConstants.DOCUMENTS_PLACEHOLDER before the advisor is used."],"exampleFix":"// before\nString instructions = \"Answer the user question using the knowledge base.\";\n// after\nString instructions = \"Answer the user question using the knowledge base:\\n{documents}\";","handlingStrategy":"validation","validationCode":"// Java\nif (instructions == null || !instructions.contains(\"{documents}\")) {\n    throw new IllegalArgumentException(\"instructions must contain {documents} placeholder\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    advisor.before(request, advisorContext);\n} catch (BizException e) {\n    if (e.getMessage().contains(\"placeholder is missing\")) {\n        // fix advisor instructions configuration\n    }\n}","preventionTips":["Keep RagConstants.DOCUMENTS_PLACEHOLDER in any custom instructions template.","Add a unit test asserting advisor instructions contain {documents}.","Use constant-based template assembly instead of free-edited strings."],"tags":["rag","prompt-template","placeholder","validation"],"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-14T05:17:10.506Z"}