spring-projects/spring-ai · error · java.lang.IllegalArgumentException

Method cannot have more than one McpMeta parameter: {method.

Error message

Method cannot have more than one McpMeta parameter: {method.getName()} in {method.getDeclaringClass().getName()}

What it means

validateParameters() permits at most one parameter assignable from McpMeta per @McpPrompt method; the framework injects the request's metadata into it. A second McpMeta parameter is ambiguous and throws IllegalArgumentException naming the method and declaring class.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/prompt/AbstractMcpPromptMethodCallback.java:140

		for (java.lang.reflect.Parameter param : parameters) {
			Class<?> paramType = param.getType();

			this.validateParamType(paramType);

			// Skip @McpProgressToken annotated parameters from validation
			if (param.isAnnotationPresent(McpProgressToken.class)) {
				if (hasProgressTokenParam) {
					throw new IllegalArgumentException("Method cannot have more than one @McpProgressToken parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasProgressTokenParam = true;
				continue;
			}

			// Skip McpMeta parameters from validation
			if (McpMeta.class.isAssignableFrom(paramType)) {
				if (hasMetaParam) {
					throw new IllegalArgumentException("Method cannot have more than one McpMeta parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasMetaParam = true;
				continue;
			}

			if (McpSyncRequestContext.class.isAssignableFrom(paramType)) {
				if (hasRequestContextParam) {
					throw new IllegalArgumentException("Method cannot have more than one request context parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				if (McpPredicates.isReactiveReturnType.test(method)) {
					throw new IllegalArgumentException(
							"Sync complete methods should use McpSyncRequestContext instead of McpAsyncRequestContext parameter: "
									+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasRequestContextParam = true;
			}

View on GitHub (pinned to 98a7beda4f)

Solutions

Keep a single McpMeta parameter and read all needed metadata keys from it.
Remove or retype the duplicate parameter to a supported non-McpMeta type.
If using a McpMeta subclass, drop the base-typed parameter so only one assignable parameter remains.

Example fix

// before
@McpPrompt(name = "p")
public String complete(String q, McpMeta meta, McpMeta meta2) { ... }
// after
@McpPrompt(name = "p")
public String complete(String q, McpMeta meta) { ... }

Defensive patterns

Strategy: validation

Validate before calling

long metaParams = Arrays.stream(method.getParameters())
    .filter(p -> McpMeta.class.isAssignableFrom(p.getType())).count();
if (metaParams > 1) throw new IllegalStateException("Only one McpMeta parameter allowed");

Try / catch

try { registry.register(bean); } catch (IllegalArgumentException e) { log.error("Invalid @McpPrompt signature: {}", e.getMessage()); }

Prevention

Declare McpMeta once and read all keys from it
Avoid mixing McpMeta with its subclasses in one signature
Review signatures after refactors for duplicated meta parameters

When it happens

Trigger: An @McpPrompt method declaring two parameters whose types are McpMeta (or subclasses of it), e.g. complete(String value, McpMeta m1, McpMeta m2).

Common situations: Accidentally declaring both McpMeta and a custom subclass of McpMeta; copy-paste duplication of a parameter; assuming multiple meta parameters receive different metadata slices.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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