spring-projects/spring-ai · error · IllegalArgumentException

Single parameter must be of type LoggingMessageNotification:

Error message

Single parameter must be of type LoggingMessageNotification: 

What it means

For 1-parameter logging handlers, validateParameters() checks that the sole parameter type is assignable to LoggingMessageNotification. A handler taking some other single object type cannot receive the MCP logging notification and is rejected with IllegalArgumentException.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/logging/AbstractMcpLoggingMethodCallback.java:105

	 * @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 either 1 or 3 parameters
		if (parameters.length != 1 && parameters.length != 3) {
			throw new IllegalArgumentException(
					"Method must have either 1 parameter (LoggingMessageNotification) or 3 parameters (LoggingLevel, String, String): "
							+ method.getName() + " in " + method.getDeclaringClass().getName() + " has "
							+ parameters.length + " parameters");
		}

		// Check parameter types
		if (parameters.length == 1) {
			// Single parameter must be LoggingMessageNotification
			if (!LoggingMessageNotification.class.isAssignableFrom(parameters[0].getType())) {
				throw new IllegalArgumentException("Single parameter must be of type LoggingMessageNotification: "
						+ method.getName() + " in " + method.getDeclaringClass().getName() + " has parameter of type "
						+ parameters[0].getType().getName());
			}
		}
		else {
			// Three parameters must be LoggingLevel, String, String
			if (!LoggingLevel.class.isAssignableFrom(parameters[0].getType())) {
				throw new IllegalArgumentException("First parameter must be of type LoggingLevel: " + method.getName()
						+ " in " + method.getDeclaringClass().getName() + " has parameter of type "
						+ parameters[0].getType().getName());
			}
			if (!String.class.isAssignableFrom(parameters[1].getType())) {
				throw new IllegalArgumentException("Second parameter must be of type String: " + method.getName()
						+ " in " + method.getDeclaringClass().getName() + " has parameter of type "
						+ parameters[1].getType().getName());
			}
			if (!String.class.isAssignableFrom(parameters[2].getType())) {
				throw new IllegalArgumentException("Third parameter must be of type String: " + method.getName()

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Change the parameter type to LoggingMessageNotification
2. Extract the message/level inside the handler from the notification object
3. Or switch to the 3-parameter (LoggingLevel, String, String) form

Example fix

// before
@McpLogging(clients = "client1")
public void onLog(String message) { ... }
// after
@McpLogging(clients = "client1")
public void onLog(LoggingMessageNotification notification) {
    String message = notification.data();
}

if (m.getParameterCount() == 1
        && !LoggingMessageNotification.class.isAssignableFrom(m.getParameterTypes()[0])) {
    throw new IllegalStateException("single param must be LoggingMessageNotification");
}

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

When it happens

Trigger: Registering a @McpLogging method with one parameter of type String, Map, or a custom DTO instead of LoggingMessageNotification.

Common situations: Developer assumes the notification payload is delivered directly as a String/Map; using a shared DTO that wraps the notification; schema change after upgrading the MCP SDK.

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

• First parameter must be of type LoggingLevel:
• Second parameter must be of type String:
• Third parameter must be of type String:
• Parameter must be of type List<McpSchema.Resource>:
• Method must not be null

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