spring-projects/spring-ai · error · IllegalArgumentException

Method must have exactly 1 parameter…

Error message

Method must have exactly 1 parameter (List<McpSchema.Resource>): 

What it means

The Spring AI MCP resource-list-changed callback registration validates that the annotated consumer method takes exactly one parameter of type List<McpSchema.Resource>. This error is thrown when the method's parameter count differs from 1. The message includes the method name, declaring class, and actual parameter count to pinpoint the offending method.

Solutions

1. Change the callback method to accept exactly one parameter of type List<McpSchema.Resource>.
2. Remove any extra parameters (e.g. server references, client names) from the method signature.
3. If no resource data is needed, still declare the single List<McpSchema.Resource> parameter and ignore it.

Example fix

// before
public void onResourcesChanged() { ... }
// after
public void onResourcesChanged(List<McpSchema.Resource> updatedResources) { ... }

Method m = bean.getClass().getMethod("onResourcesChanged", List.class);
if (m.getParameterCount() != 1) throw new IllegalStateException("callback must take exactly one List<McpSchema.Resource>");

When it happens

Trigger: Registering an @McpResourceListChanged (async/sync) callback method whose signature has 0 parameters or 2+ parameters; validateParameters is invoked during builder construction via validateMethod.

Common situations: Developers write consumer methods with no arguments expecting a push notification, or add extra parameters like a client id or McpSyncServer alongside the resource list, mirroring other MCP callback styles.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Method must have either 1 parameter (ProgressNotification)…
• Single parameter must be of type ProgressNotification
• Async complete methods should use McpAsyncRequestContext…
• Async prompt method must not declare parameter of type
• Bean must not be null

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

Appendix: source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/changed/resource/AbstractMcpResourceListChangedMethodCallback.java:95

	 * Validates that the method return type is compatible with the resource list changed
	 * consumer callback. This method should be implemented by subclasses to handle
	 * specific return type validation.
	 * @param method The method to validate
	 * @throws IllegalArgumentException if the return type is not compatible
	 */
	protected abstract void validateReturnType(Method method);

	/**
	 * Validates method parameters. This method provides common validation logic.
	 * @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 exactly 1 parameter
		if (parameters.length != 1) {
			throw new IllegalArgumentException(
					"Method must have exactly 1 parameter (List<McpSchema.Resource>): " + method.getName() + " in "
							+ method.getDeclaringClass().getName() + " has " + parameters.length + " parameters");
		}

		// Check parameter type - must be List<McpSchema.Resource>
		Class<?> paramType = parameters[0].getType();
		if (!List.class.isAssignableFrom(paramType)) {
			throw new IllegalArgumentException("Parameter must be of type List<McpSchema.Resource>: " + method.getName()
					+ " in " + method.getDeclaringClass().getName() + " has parameter of type " + paramType.getName());
		}
	}

	/**
	 * Builds the arguments array for invoking the method.
	 * <p>
	 * This method constructs an array of arguments based on the method's parameter types
	 * and the available values.
	 * @param method The method to build arguments for

View on GitHub (pinned to 98a7beda4f)