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 ${declaringClass}

What it means

A @McpResource method declared more than one McpSyncRequestContext (or compatible request-context) parameter. Only one request context is provided per invocation, so validateParametersWithoutUriVariables throws IllegalArgumentException on the second occurrence.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/resource/AbstractMcpResourceMethodCallback.java:212

		// Check parameter types
		boolean hasValidParams = false;
		boolean hasExchangeParam = false;
		boolean hasRequestOrUriParam = false;
		boolean hasMetaParam = false;
		boolean hasRequestContextParam = false;

		for (Parameter param : parameters) {
			// Skip @McpProgressToken annotated parameters
			if (param.isAnnotationPresent(McpProgressToken.class)) {
				continue;
			}

			Class<?> paramType = param.getType();

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

View on GitHub (pinned to 98a7beda4f)

Solutions

Remove the duplicate McpSyncRequestContext parameter, keeping exactly one.
Move shared data into method-local variables or a service rather than extra context parameters.
If a second context-like value is needed, derive it from the single context inside the method body.

Example fix

// before
@McpResource(uri = "file:///docs/{name}")
public String read(McpSyncRequestContext ctx, McpSyncRequestContext ctx2, String name) { ... }

// after
@McpResource(uri = "file:///docs/{name}")
public String read(McpSyncRequestContext ctx, String name) { ... }

Defensive patterns

Strategy: validation

Validate before calling

static long countContextParams(Method m) {
    return java.util.Arrays.stream(m.getParameterTypes())
        .filter(t -> McpSyncRequestContext.class.isAssignableFrom(t)).count();
}
// assert countContextParams(m) <= 1;

Try / catch

try {
    resourceManager.register(callback);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("Duplicate McpSyncRequestContext parameter", e);
}

Prevention

Declare exactly one request-context parameter per resource method.
Check for duplicated parameters after refactors.
Derive extra context data from the single context object in the body.

When it happens

Trigger: Declaring two parameters of type McpSyncRequestContext (or subtypes) in a resource method; the validator tracks a hasRequestContextParam flag and throws when a second context-typed parameter is seen.

Common situations: Copy-paste duplication of a context parameter; refactoring that added a context parameter without removing the old one; confusion between progress-token/meta special params and the request context.

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