spring-projects/spring-ai · error · IllegalArgumentException

Method cannot have more than one CompleteRequest parameter:

Error message

Method cannot have more than one CompleteRequest parameter: {method} in {class}

What it means

Thrown while validating an @McpComplete-annotated method's signature: the parameter scan in validateParameters found a second parameter whose type is assignable to CompleteRequest. Each supported parameter type is tracked with a boolean flag (e.g. hasRequestParam), and this guard fires when that flag is already true for a later CompleteRequest-typed parameter — the callback factory cannot decide which of the duplicates should receive the parsed request.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/complete/AbstractMcpCompleteMethodCallback.java:241

				hasRequestContextParam = true;
			}
			else if (McpTransportContext.class.isAssignableFrom(paramType)) {
				if (hasTransportContext) {
					throw new IllegalArgumentException("Method cannot have more than one transport context parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasTransportContext = true;
			}
			else if (isExchangeType(paramType)) {
				if (hasExchangeParam) {
					throw new IllegalArgumentException("Method cannot have more than one exchange parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasExchangeParam = true;
			}
			else if (CompleteRequest.class.isAssignableFrom(paramType)) {
				if (hasRequestParam) {
					throw new IllegalArgumentException("Method cannot have more than one CompleteRequest parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasRequestParam = true;
			}
			else if (CompleteRequest.CompleteArgument.class.isAssignableFrom(paramType)) {
				if (hasArgumentParam) {
					throw new IllegalArgumentException("Method cannot have more than one CompleteArgument parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasArgumentParam = true;
			}
			else if (!String.class.isAssignableFrom(paramType)) {
				throw new IllegalArgumentException(
						"Method parameters must be exchange, CompleteRequest, CompleteArgument, or String: "
								+ method.getName() + " in " + method.getDeclaringClass().getName()
								+ " has parameter of type " + paramType.getName());
			}
		}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Remove the duplicate CompleteRequest parameter, keeping one
2. Rebuild the callback

Example fix

// before
public String complete(CompleteRequest r1, CompleteRequest r2) { ... }
// after
public String complete(CompleteRequest request) { ... }

long r = Arrays.stream(m.getParameterTypes()).filter(CompleteRequest.class::isAssignableFrom).count();
if (r > 1) throw new IllegalStateException("Only one CompleteRequest parameter allowed: " + m);

try {
    callbackBuilder.build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("more than one CompleteRequest")) { /* keep a single CompleteRequest */ }
    throw e;
}

When it happens

Trigger: A method signature includes two parameters assignable to CompleteRequest.

Common situations: Copy-paste of signatures; adding the request explicitly while an inherited/generated one already exists.

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

• Method cannot have more than one transport context parameter
• Method cannot have more than one exchange parameter: {method
• Method cannot have more than one CompleteArgument parameter:
• Method cannot have more than one @McpProgressToken parameter
• Method cannot have more than one McpMeta parameter: {method}

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