spring-projects/spring-ai · error · IllegalArgumentException

Failed to assign all URI variables to method parameters. Ass

Error message

Failed to assign all URI variables to method parameters. Assigned: ${assigned}, Expected: ${expected}

What it means

Thrown at invocation time by buildArgsWithUriVariables when URI variable values from the incoming request could not all be matched/assigned to method parameters. The number of assigned variables differs from the template's declared URI variables.

Source

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

			// handled)
			// or if it's already assigned (exchange or request)
			if (parameters[i].isAnnotationPresent(McpProgressToken.class)
					|| McpMeta.class.isAssignableFrom(parameters[i].getType()) || args[i] != null) {
				continue;
			}

			// Assign the next URI variable
			if (variableIndex < this.uriVariables.size()) {
				String variableName = this.uriVariables.get(variableIndex);
				args[i] = uriVariableValues.get(variableName);
				assignedVariables.add(variableName);
				variableIndex++;
			}
		}

		// Verify all URI variables were assigned
		if (assignedVariables.size() != this.uriVariables.size()) {
			throw new IllegalArgumentException("Failed to assign all URI variables to method parameters. "
					+ "Assigned: " + assignedVariables + ", Expected: " + this.uriVariables);
		}
	}

	/**
	 * Builds arguments for methods without URI variables. This method provides common
	 * argument building logic for methods without URI variables.
	 * @param parameters The method parameters
	 * @param args The arguments array to populate
	 * @param exchange The server exchange
	 * @param request The resource request
	 */
	protected void buildArgsWithoutUriVariables(Parameter[] parameters, Object[] args, Object exchange,
			ReadResourceRequest request) {
		for (int i = 0; i < parameters.length; i++) {
			// Skip if parameter is annotated with @McpProgressToken or is McpMeta
			// (already handled)
			if (parameters[i].isAnnotationPresent(McpProgressToken.class)

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Check the client's requested URI fully matches the resource template including every variable segment
2. Log and inspect uriVariableValues to see which variable is missing
3. Re-register the resource with a corrected @McpResource uri template consistent with the method signature

Example fix

// client request causing failure: docs/read (template docs/{page})
// fix client call to include the variable:
// before: resources/read?uri=docs/read
// after:  resources/read?uri=docs/intro

McpUriTemplateManager tm = new DefaultMcpUriTemplateManagerFactory().create(templateUri);
if (!tm.matches(requestedUri)) throw new IllegalArgumentException("URI " + requestedUri + " does not match template " + templateUri);

try {
    Object result = callback.call(exchange, request);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Failed to assign all URI variables")) {
        return errorResponse(INVALID_PARAMS, "Resource URI must match template: " + e.getMessage());
    }
    throw e;
}

When it happens

Trigger: A client requests a URI whose extracted variable values don't map onto the method's String parameters (e.g. template has {a}/{b} but the resolved request only yields one value, or a value is null/missing), so assignedVariables.size() != this.uriVariables.size().

Common situations: Client calling a resource URI that doesn't fully match the template (missing path segment); template variables with unsupported patterns; mismatch between the uriVariables list used at registration and the runtime URI.

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 parameters for all URI variables. Expected
• URI variable parameters must be of type String: ${method} in
• URI must not be null or empty
• Failed to extract all URI variables from request URI: {uri}.
• Method must have exactly 1 parameter (List<McpSchema.Resourc

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