spring-projects/spring-ai · error · IllegalArgumentException

Currently only methods with a single CreateMessageRequest pa

Error message

Currently only methods with a single CreateMessageRequest parameter are supported

What it means

buildArgs() assembles the runtime arguments passed to the annotated sampling method and only implements the single CreateMessageRequest-parameter case. If the method's parameter count is not 1 at invocation time it throws IllegalArgumentException. This is a defensive runtime check mirroring the earlier validateParameters() registration-time validation.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/sampling/AbstractMcpSamplingMethodCallback.java:140

	 * and the available values (exchange, request).
	 * @param method The method to build arguments for
	 * @param exchange The server exchange
	 * @param request The sampling request
	 * @return An array of arguments for the method invocation
	 */
	protected Object[] buildArgs(Method method, Object exchange, CreateMessageRequest request) {
		Parameter[] parameters = method.getParameters();
		Object[] args = new Object[parameters.length];

		if (parameters.length == 1) {
			// Single parameter (CreateMessageRequest)
			args[0] = request;
		}
		else {
			// TODO: Support for multiple parameters corresponding to CreateMessageRequest
			// fields
			// For now, we only support the single parameter version
			throw new IllegalArgumentException(
					"Currently only methods with a single CreateMessageRequest parameter are supported");
		}

		return args;
	}

	/**
	 * Checks if a parameter type is compatible with the exchange type. This method should
	 * be implemented by subclasses to handle specific exchange type checking.
	 * @param paramType The parameter type to check
	 * @return true if the parameter type is compatible with the exchange type, false
	 * otherwise
	 */
	protected abstract boolean isExchangeType(Class<?> paramType);

	/**
	 * Exception thrown when there is an error invoking a sampling method.
	 */

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Ensure the sampling method has exactly one CreateMessageRequest parameter
2. If writing a custom callback subclass, call validateParameters() (or replicate the count==1 contract) before invocation
3. Treat this as a bug report trigger: file an issue with the method signature if validation passed but buildArgs still throws

Example fix

// before
Method m = beanClass.getMethod("handle", CreateMessageRequest.class, String.class);
new AbstractMcpSamplingMethodCallback(builder.method(m)); // skips validation
// after
new AbstractMcpSamplingMethodCallback(builder.method(beanClass.getMethod("handle", CreateMessageRequest.class))); // validateMethod enforces single param

if (method.getParameterCount() != 1
        || !CreateMessageRequest.class.isAssignableFrom(method.getParameterTypes()[0])) {
    throw new IllegalStateException("Callback method must take exactly one CreateMessageRequest");
}

try {
    Object result = callback.call(request);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("single CreateMessageRequest parameter are supported")) {
        throw new IllegalStateException("Misconfigured sampling callback: " + callback, e);
    } else { throw e; }
}

When it happens

Trigger: Invoking a sampling callback whose method declares 0 or 2+ parameters — typically possible only when a subclass overrides validation or the method was mutated/registered without running validateMethod.

Common situations: Custom subclasses of AbstractMcpSamplingMethodCallback that skip or weaken validateParameters() then fail at call time; framework-internal invariant breach when reflection metadata desyncs from the built args array.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Method must have at least 1 parameter (CreateMessageRequest)
• Currently only methods with a single CreateMessageRequest pa
• Error invoking resource list changed consumer method: " + th
• Error invoking tool list changed consumer method:
• Method must not be null

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