spring-projects/spring-ai · error · IllegalArgumentException

Either prompt or uri must be provided in McpComplete annotat

Error message

Either prompt or uri must be provided in McpComplete annotation

What it means

CompleteAdapter.asCompleteReference converts an @McpComplete annotation into an MCP completion reference. The MCP spec requires a completion request to target exactly one of a prompt name or a resource URI. This error is thrown when the McpComplete annotation specifies neither a prompt nor a uri.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/adapter/CompleteAdapter.java:52

	private CompleteAdapter() {
	}

	/**
	 * Convert a McpComplete annotation to a McpSchema.CompleteReference object.
	 * @param mcpComplete The McpComplete annotation
	 * @return The corresponding McpSchema.CompleteReference object
	 * @throws IllegalArgumentException if neither prompt nor uri is provided, or if both
	 * are provided
	 */
	public static McpSchema.CompleteReference asCompleteReference(McpComplete mcpComplete) {
		Assert.notNull(mcpComplete, "mcpComplete cannot be null");

		String prompt = mcpComplete.prompt();
		String uri = mcpComplete.uri();

		// Validate that either prompt or uri is provided, but not both
		if ((prompt == null || prompt.isEmpty()) && (uri == null || uri.isEmpty())) {
			throw new IllegalArgumentException("Either prompt or uri must be provided in McpComplete annotation");
		}
		if ((prompt != null && !prompt.isEmpty()) && (uri != null && !uri.isEmpty())) {
			throw new IllegalArgumentException("Only one of prompt or uri can be provided in McpComplete annotation");
		}

		// Create the appropriate reference type based on what's provided
		if (prompt != null && !prompt.isEmpty()) {
			return McpSchema.PromptReference.builder(prompt).build();
		}
		else {
			return new McpSchema.ResourceReference(uri);
		}
	}

	/**
	 * Convert a McpComplete annotation and Method to a McpSchema.CompleteReference
	 * object.
	 * @param mcpComplete The McpComplete annotation

View on GitHub (pinned to 98a7beda4f)

Solutions

Set either the prompt or uri attribute on the @McpComplete annotation, e.g. @McpComplete(prompt = "my-prompt")
If the completion targets a resource, set uri instead: @McpComplete(uri = "file:///logs/{path}")
Remove the @McpComplete annotation entirely if no completion is intended

Example fix

// before
@McpComplete
public List<String> complete(String argument) { ... }

// after
@McpComplete(prompt = "code-review")
public List<String> complete(String argument) { ... }

Defensive patterns

Strategy: validation

Validate before calling

McpComplete ann = ...;
boolean promptSet = ann.prompt() != null && !ann.prompt().isEmpty();
boolean uriSet = ann.uri() != null && !ann.uri().isEmpty();
if (!promptSet && !uriSet) {
    throw new IllegalStateException("@McpComplete requires prompt or uri");
}

Prevention

Always pass exactly one of prompt or uri when writing @McpComplete
Add a unit test that builds the reference for every annotated method
Rely on compile-time constants for the attribute values

When it happens

Trigger: Annotating a method with @McpComplete but leaving both prompt() and uri() at their defaults (null or empty string), then the adapter calls asCompleteReference during annotation processing.

Common situations: Developer adds @McpComplete for autocompletion support but forgets to fill in the prompt attribute; refactoring moves the prompt name out and leaves the annotation empty; copying an annotation template without editing its fields.

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