spring-projects/spring-ai · error · IllegalArgumentException

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

Error message

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

What it means

validateParameters also checks the single parameter's type: it must be assignable from List (the prompt list). A handler whose sole parameter is a different type (e.g. List<String>, Prompt[], or a non-list custom type) cannot receive List<McpSchema.Prompt> and is rejected.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/changed/prompt/AbstractMcpPromptListChangedMethodCallback.java:102

	/**
	 * 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.Prompt>): " + method.getName() + " in "
							+ method.getDeclaringClass().getName() + " has " + parameters.length + " parameters");
		}

		// Check parameter type - must be List<McpSchema.Prompt>
		Class<?> paramType = parameters[0].getType();
		if (!List.class.isAssignableFrom(paramType)) {
			throw new IllegalArgumentException("Parameter must be of type List<McpSchema.Prompt>: " + 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 updatedPrompts The updated list of prompts
	 * @return An array of arguments for the method invocation
	 */
	protected Object[] buildArgs(Method method, Object exchange, List<McpSchema.Prompt> updatedPrompts) {
		Parameter[] parameters = method.getParameters();
		Object[] args = new Object[parameters.length];

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Declare the parameter as List<McpSchema.Prompt> (or a subtype/assignable List type)
2. Fix the import so the parameter uses the MCP spec McpSchema.Prompt, not a locally defined Prompt class
3. Prefer the fully typed List<McpSchema.Prompt> over a raw List even though a raw List passes the check

Example fix

// before
public void onPromptListChanged(List<String> promptNames) { ... }
// after
public void onPromptListChanged(List<McpSchema.Prompt> prompts) { ... }

if (method.getParameterCount() == 1 && !List.class.isAssignableFrom(method.getParameterTypes()[0])) { throw new IllegalArgumentException("Parameter must be List<McpSchema.Prompt>"); }

boolean paramIsPromptList = m.getParameterCount() == 1 && List.class.isAssignableFrom(m.getParameterTypes()[0]);

try { registerCallback(method); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Parameter must be of type")) { log.error("Fix handler to accept List<McpSchema.Prompt>"); } throw e; }

When it happens

Trigger: Registering a one-parameter handler whose parameter is not a List (e.g. a raw array, a String, or a list of the wrong element type such as List<String>).

Common situations: Developers guess the callback signature instead of copying the documented one; same-named custom Prompt classes shadowing the expected McpSchema.Prompt type.

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

• Method must have exactly 1 parameter (List<McpSchema.Prompt>
• Parameter must be of type List<McpSchema.Tool>: " + method.g
• Single parameter must be of type ProgressNotification: {meth
• Required no-arg constructor not found in
• instantiation failed

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