spring-projects/spring-ai · error · IllegalArgumentException

Method cannot have more than one ReadResourceRequest or Stri

Error message

Method cannot have more than one ReadResourceRequest or String parameter: ${method} in ${declaringClass}

What it means

Thrown when a resource method with no URI variables declares more than one parameter of type ReadResourceRequest or String. Only one parameter receives the read request (or the URI string), so a second one is ambiguous and rejected during validation.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/resource/AbstractMcpResourceMethodCallback.java:251

			}
			else if (McpMeta.class.isAssignableFrom(paramType)) {
				if (hasMetaParam) {
					throw new IllegalArgumentException("Method cannot have more than one McpMeta parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasMetaParam = true;
			}
			else if (isExchangeOrContextType(paramType)) {
				if (hasExchangeParam) {
					throw new IllegalArgumentException("Method cannot have more than one exchange parameter: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasExchangeParam = true;
			}
			else if (ReadResourceRequest.class.isAssignableFrom(paramType)
					|| String.class.isAssignableFrom(paramType)) {
				if (hasRequestOrUriParam) {
					throw new IllegalArgumentException(
							"Method cannot have more than one ReadResourceRequest or String parameter: "
									+ method.getName() + " in " + method.getDeclaringClass().getName());
				}
				hasRequestOrUriParam = true;
				hasValidParams = true;
			}
			else {
				throw new IllegalArgumentException(
						"Method parameters must be exchange, ReadResourceRequest, String, McpMeta, or @McpProgressToken when no URI variables are present: "
								+ method.getName() + " in " + method.getDeclaringClass().getName()
								+ " has parameter of type " + paramType.getName());
			}
		}

		if (!hasValidParams && nonSpecialParamCount > 0) {
			throw new IllegalArgumentException(
					"Method must have either ReadResourceRequest or String parameter when no URI variables are present: "
							+ method.getName() + " in " + method.getDeclaringClass().getName());

View on GitHub (pinned to 98a7beda4f)

Solutions

Keep exactly one ReadResourceRequest or String parameter and remove the other
If you need the raw URI and the request object, extract the URI from the ReadResourceRequest instead of a second parameter

Example fix

// before
public String read(ReadResourceRequest req, String uri) { ... }
// after
public String read(ReadResourceRequest req) { return req.uri(); ... }

Defensive patterns

Strategy: validation

Validate before calling

long reqCount = Arrays.stream(method.getParameterTypes())
    .filter(t -> ReadResourceRequest.class.isAssignableFrom(t) || String.class.isAssignableFrom(t))
    .count();
if (reqCount > 1) throw new IllegalStateException(method + " declares " + reqCount + " request/URI parameters");

Try / catch

try { provider.build(...); }
catch (IllegalArgumentException e) {
  if (e.getMessage().contains("more than one ReadResourceRequest or String parameter")) { /* keep one request param */ }
  else throw e;
}

Prevention

Choose either ReadResourceRequest or String for the resource payload, not both
Extract URI details from ReadResourceRequest instead of adding a second String parameter

When it happens

Trigger: A @McpResource method (no URI variables) has two ReadResourceRequest and/or String parameters (e.g. ReadResourceRequest + String, or two Strings); triggered when hasRequestOrUriParam is already true.

Common situations: Adding a String uri parameter to a method that already takes ReadResourceRequest; leaving a second String param from a refactored signature; copy-paste duplication.

Understand the failure class

Background: "must be a positive integer", "cannot be empty", "invalid argument": how invalid-argument errors work across open-source libraries — this error's family across 33 libraries.

Related errors

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