spring-projects/spring-ai · error · IllegalArgumentException

The following placeholders must be present in the prompt…

Error message

The following placeholders must be present in the prompt template: %s

What it means

PromptAssert.templateHasRequiredPlaceholders validates that every placeholder the caller declares is literally present in the prompt template's text. If any declared placeholder is missing from the template string, an IllegalArgumentException lists all missing placeholders.

Solutions

Re-add the missing placeholder to the template exactly as declared (e.g. {question_answer_context})
Fix placeholder spelling/casing to match the required name
Use the library's default template if unsure which placeholders are mandatory
If using a different template syntax, ensure the raw template text contains the placeholder string verbatim

Example fix

// before
String template = "Answer the question: {user_query}"; // missing required placeholder
// after
String template = "Answer the question: {query} using context: {question_answer_context}";

Defensive patterns

Strategy: validation

Validate before calling

List<String> missing = Stream.of("query", "question_answer_context")
    .filter(p -> !template.getTemplate().contains(p)).toList();
if (!missing.isEmpty()) throw new IllegalStateException("Template missing: " + missing);

Try / catch

try { advisor.advise(query, context); } catch (IllegalArgumentException e) {
    if (e.getMessage().contains("placeholders must be present")) { /* restore placeholders in template */ }
}

Prevention

Start from the library's default RAG template and only append text, never remove placeholders
Add a unit test asserting required placeholders exist in custom templates
Watch out when switching template engines — placeholder syntax must still match literally

When it happens

Trigger: Calling templateHasRequiredPlaceholders (used by RAG components like RetrievalAugmentationAdvisor's query transformer/rag prompt) with a template that lacks one of the required variables, e.g. {query} or {question_answer_context} removed or renamed during prompt customization.

Common situations: Users editing the built-in RAG prompt templates and deleting or misspelling required placeholders like 'question_answer_context'; custom prompts that use different variable names; delimiters differing ({var} vs {{var}}) so the literal text check fails.

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

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/edc785e87d25f241. Report an issue: GitHub.

Appendix: source

Thrown at spring-ai-rag/src/main/java/org/springframework/ai/rag/util/PromptAssert.java:54

	/**
	 * Assert that the given prompt template contains the required placeholders.
	 * @param promptTemplate the prompt template to check
	 * @param placeholders the placeholders that must be present in the prompt template
	 */
	public static void templateHasRequiredPlaceholders(PromptTemplate promptTemplate, String... placeholders) {
		Assert.notNull(promptTemplate, "promptTemplate cannot be null");
		Assert.notEmpty(placeholders, "placeholders cannot be null or empty");

		List<String> missingPlaceholders = new ArrayList<>();
		for (String placeholder : placeholders) {
			if (!promptTemplate.getTemplate().contains(placeholder)) {
				missingPlaceholders.add(placeholder);
			}
		}

		if (!missingPlaceholders.isEmpty()) {
			throw new IllegalArgumentException("The following placeholders must be present in the prompt template: %s"
				.formatted(String.join(",", missingPlaceholders)));
		}
	}

}

View on GitHub (pinned to 98a7beda4f)