spring-projects/spring-ai · error · IllegalArgumentException

Parameter must be of type List<McpSchema.Resource>:

Error message

Parameter must be of type List<McpSchema.Resource>: 

What it means

The resource-list-changed callback's single parameter must be a List (assignable from java.util.List), intended to carry McpSchema.Resource entries. This error is thrown when the parameter type is something else. The message names the method, class, and the actual parameter type.

Source

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

	/**
	 * 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
	 * @param exchange The server exchange
	 * @param updatedResources The updated list of resources
	 * @return An array of arguments for the method invocation
	 */
	protected Object[] buildArgs(Method method, Object exchange, List<McpSchema.Resource> updatedResources) {
		Parameter[] parameters = method.getParameters();
		Object[] args = new Object[parameters.length];

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Change the parameter to List<McpSchema.Resource> (java.util.List of org.springframework.ai.mcp.McpSchema.Resource).
2. Verify the import: use McpSchema.Resource, not another class named Resource.
3. If you want per-resource handling, accept the full list and iterate inside the method.

Example fix

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

Method m = bean.getClass().getMethod("onResourcesChanged", List.class);
if (!List.class.isAssignableFrom(m.getParameterTypes()[0])) throw new IllegalStateException("parameter must be a List");

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

When it happens

Trigger: Registering a callback method whose sole parameter is not a List, e.g. a single McpSchema.Resource, ResourceReference, String, or a custom DTO; checked in validateParameters during callback building.

Common situations: Confusing this callback with resource-read callbacks that receive a single resource; using List<Resource> from a different package (e.g. Spring core.io.Resource) instead of McpSchema.Resource.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• List items must be of type String
• List items must be of type String
• List items must be of type String
• Single parameter must be of type LoggingMessageNotification:
• First parameter must be of type LoggingLevel:

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