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

Method cannot have more than one GetPromptRequest parameter:

Error message

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

What it means

AbstractMcpPromptMethodCallback.validateParameters enforces at most one GetPromptRequest parameter in a prompt method. If a second parameter assignable to GetPromptRequest is found, registration fails with this IllegalArgumentException, because the callback binds the single incoming GetPromptRequest to only one parameter and a duplicate would be ambiguous.

Source

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

							+ 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());
				}
				hasRequestContextParam = true;
			}
			else if (isSupportedExchangeOrContextType(paramType)) {
				if (hasExchangeParam) {
					throw new IllegalArgumentException("Method cannot have more than one exchange parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasExchangeParam = true;
			}
			else if (GetPromptRequest.class.isAssignableFrom(paramType)) {
				if (hasRequestParam) {
					throw new IllegalArgumentException("Method cannot have more than one GetPromptRequest parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasRequestParam = true;
			}
			else if (Map.class.isAssignableFrom(paramType)) {
				if (hasMapParam) {
					throw new IllegalArgumentException("Method cannot have more than one Map parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasMapParam = true;
			}
			// Other parameter types are assumed to be individual arguments
		}
	}

	protected abstract Object assignExchangeType(Class<?> paramType, Object exchange);

	/**

View on GitHub (pinned to 98a7beda4f)

Solutions

Remove the duplicate GetPromptRequest parameter and pass the request data as individual @McpArg parameters or a Map if needed.
If you intended distinct data, declare individual typed parameters (@McpArg String name, int max) instead of a second request object.
Ensure no custom class extending GetPromptRequest is declared alongside a raw GetPromptRequest parameter.

Example fix

// before
@McpPrompt(name = "code-review")
public String review(GetPromptRequest request, GetPromptRequest request2) { ... }
// after
@McpPrompt(name = "code-review")
public String review(GetPromptRequest request) { ... }

Defensive patterns

Strategy: validation

Validate before calling

long reqParams = Arrays.stream(method.getParameters())
    .map(Parameter::getType)
    .filter(t -> GetPromptRequest.class.isAssignableFrom(t))
    .count();
if (reqParams > 1) throw new IllegalStateException(method + " declares multiple GetPromptRequest parameters");

Prevention

Use exactly one GetPromptRequest parameter, or prefer individual @McpArg parameters.
Avoid custom classes extending GetPromptRequest in handler signatures.
Write a unit test that builds every prompt callback at context startup.

When it happens

Trigger: Registering a prompt method like `myPrompt(GetPromptRequest req1, GetPromptRequest req2)`; the check fires in the `GetPromptRequest.class.isAssignableFrom(paramType)` branch when hasRequestParam is already true.

Common situations: Copy-paste when adding a parameter 'for convenience'; refactoring where a wrapper type accidentally extends/implements GetPromptRequest so two parameters both satisfy isAssignableFrom; merging two prompt handlers into one method.

Understand the failure class

Background: "must be a positive integer", "cannot be empty", "invalid argument": how invalid-argument errors work across open-source libraries — this error's family across 33 libraries.

Related errors

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