spring-projects/spring-ai · error · IllegalArgumentException

Single parameter must be of type ElicitRequest:

Error message

Single parameter must be of type ElicitRequest: 

What it means

Thrown by AbstractMcpElicitationMethodCallback.validateParameters when an @McpElicitation-annotated method declares exactly one parameter whose type is not (a subtype of) ElicitRequest. The elicitation callback framework invokes handler methods reflectively with a single McpSchema.ElicitRequest argument, so a single-parameter method must accept it.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/elicitation/AbstractMcpElicitationMethodCallback.java:102

	 * delegates exchange type checking to subclasses.
	 * @param method The method to validate
	 * @throws IllegalArgumentException if the parameters are not compatible
	 */
	protected void validateParameters(Method method) {
		Parameter[] parameters = method.getParameters();

		// Check parameter count - must have at least 1 parameter
		if (parameters.length < 1) {
			throw new IllegalArgumentException(
					"Method must have at least 1 parameter (ElicitRequest): " + method.getName() + " in "
							+ method.getDeclaringClass().getName() + " has " + parameters.length + " parameters");
		}

		// Check parameter types
		if (parameters.length == 1) {
			// Single parameter must be ElicitRequest
			if (!ElicitRequest.class.isAssignableFrom(parameters[0].getType())) {
				throw new IllegalArgumentException("Single parameter must be of type ElicitRequest: " + method.getName()
						+ " in " + method.getDeclaringClass().getName() + " has parameter of type "
						+ parameters[0].getType().getName());
			}
		}
		else {
			// TODO: Support for multiple parameters corresponding to ElicitRequest
			// fields
			// For now, we only support the single parameter version
			throw new IllegalArgumentException(
					"Currently only methods with a single ElicitRequest parameter are supported: " + method.getName()
							+ " in " + method.getDeclaringClass().getName() + " has " + parameters.length
							+ " parameters");
		}
	}

	/**
	 * Builds the arguments array for invoking the method.
	 * <p>

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Change the single method parameter to io.modelcontextprotocol.spec.McpSchema.ElicitRequest
2. Access elicited values via request.params() (the Map) instead of declaring a custom parameter type
3. If you declared zero parameters, add the single ElicitRequest parameter (though zero-parameter paths take the else branch differently, ensure length==1)
4. Check the library version for any newer support of structured/custom elicitation parameter types before attempting workarounds

Example fix

// before
@McpElicitation
public ElicitResult confirm(ConfirmRequest request) { ... }

// after
@McpElicitation
public ElicitResult confirm(ElicitRequest request) {
    Object value = request.params() != null ? request.params().get("confirm") : null;
    ...
}

if (m.getParameterCount() == 1 && !ElicitRequest.class.isAssignableFrom(m.getParameterTypes()[0])) {
    throw new IllegalArgumentException("Handler must take a single ElicitRequest: " + m);
}

boolean isValidElicitationMethod(Method m) {
    return m.getParameterCount() == 1
        && ElicitRequest.class.isAssignableFrom(m.getParameterTypes()[0]);
}

When it happens

Trigger: Registering an elicitation handler method with exactly one parameter typed as anything other than ElicitRequest (e.g. a String, Map, or a custom request DTO), e.g. @McpElicitation public ElicitResult handle(MyRequest req).

Common situations: Developers assume the framework deserializes the client's elicitation payload into a custom POJO parameter (that multi-parameter support is a TODO and not implemented), or they copy an MCP tool callback signature where typed arguments are supported.

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

• Currently only methods with a single ElicitRequest parameter
• Method must have exactly 1 parameter (List<McpSchema.Resourc
• Method must not be null
• Method must have at least 1 parameter (ElicitRequest):
• Currently only methods with a single ElicitRequest parameter

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