spring-projects/spring-ai · error · IllegalArgumentException

Method cannot have more than one request context parameter:

Error message

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

What it means

Only one McpSyncRequestContext parameter is permitted per completion method; the framework injects the request context once. validateParameters() throws this IllegalArgumentException when a second McpSyncRequestContext-typed parameter is detected (message names the method and class).

Source

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

							+ 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(
							"Async complete methods should use McpAsyncRequestContext instead of McpSyncRequestContext parameter: "
									+ method.getName() + " in " + method.getDeclaringClass().getName());
				}

				hasRequestContextParam = true;
			}
			else if (McpAsyncRequestContext.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.isNotReactiveReturnType.test(method)) {
					throw new IllegalArgumentException(
							"Sync complete methods should use McpSyncRequestContext instead of McpAsyncRequestContext parameter: "

View on GitHub (pinned to 98a7beda4f)

Solutions

Keep exactly one McpSyncRequestContext parameter and remove the duplicate.
Access all request data (arguments, progress, logging) through the single context instance.
If using a reactive return type, replace McpSyncRequestContext with McpAsyncRequestContext (see the companion async error).

Example fix

// before
public void complete(String value, McpSyncRequestContext ctx1, McpSyncRequestContext ctx2) { }
// after
public void complete(String value, McpSyncRequestContext ctx) { }

Defensive patterns

Strategy: validation

Validate before calling

long ctxs = Arrays.stream(method.getParameters())
    .filter(p -> McpSyncRequestContext.class.isAssignableFrom(p.getType())).count();
if (ctxs > 1) throw new IllegalStateException("duplicate request context parameter in " + method.getName());

Prevention

Declare the request context parameter at most once.
Use McpAsyncRequestContext for reactive return types.
Read all request state from the single context instance.

When it happens

Trigger: Declaring two McpSyncRequestContext parameters on a single @McpComplete-annotated method and registering it.

Common situations: Duplicated context parameter after refactoring or merging branches; misunderstanding that the context aggregates request state so one instance suffices.

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