spring-projects/spring-ai · error · IllegalArgumentException

Found 2 sampling handlers for client [%s], found in bean wit

Error message

Found 2 sampling handlers for client [%s], found in bean with names %s. Only one @McpSampling handler is allowed per client

What it means

Same duplicate-detection mechanism as elicitation but for @McpSampling handlers: AbstractClientMcpHandlerRegistry.postProcessBeanFactory requires at most one sampling handler per MCP client. When samplingClientToAnnotatedBeans contains two or more beans for the same client it throws IllegalArgumentException with the client name and conflicting bean names, failing at startup.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/spring/AbstractClientMcpHandlerRegistry.java:111

				}
				else if (foundAnnotation instanceof McpElicitation elicitation) {
					for (var client : elicitation.clients()) {
						elicitationClientToAnnotatedBeans.computeIfAbsent(client, c -> new ArrayList<>()).add(beanName);
					}
				}
			}
		}

		for (var elicitationEntry : elicitationClientToAnnotatedBeans.entrySet()) {
			if (elicitationEntry.getValue().size() > 1) {
				throw new IllegalArgumentException(
						"Found 2 elicitation handlers for client [%s], found in bean with names %s. Only one @McpElicitation handler is allowed per client"
							.formatted(elicitationEntry.getKey(), new LinkedHashSet<>(elicitationEntry.getValue())));
			}
		}
		for (var samplingEntry : samplingClientToAnnotatedBeans.entrySet()) {
			if (samplingEntry.getValue().size() > 1) {
				throw new IllegalArgumentException(
						"Found 2 sampling handlers for client [%s], found in bean with names %s. Only one @McpSampling handler is allowed per client"
							.formatted(samplingEntry.getKey(), new LinkedHashSet<>(samplingEntry.getValue())));
			}
		}

		Map<String, McpSchema.ClientCapabilities.Builder> capsPerClient = new HashMap<>();
		for (var samplingClient : samplingClientToAnnotatedBeans.keySet()) {
			capsPerClient.computeIfAbsent(samplingClient, ignored -> McpSchema.ClientCapabilities.builder()).sampling();
		}
		for (var elicitationClient : elicitationClientToAnnotatedBeans.keySet()) {
			capsPerClient.computeIfAbsent(elicitationClient, ignored -> McpSchema.ClientCapabilities.builder())
				.elicitation();
		}

		this.capabilitiesPerClient = capsPerClient.entrySet()
			.stream()
			.collect(Collectors.toMap(Map.Entry::getKey, entry -> entry.getValue().build()));
	}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Delete or exclude one of the duplicate @McpSampling beans (bean names are given in the message).
2. Merge sampling logic into one @McpSampling handler per client.
3. Assign the handlers to different client names if they were meant for distinct clients.

Example fix

// before
@Bean SamplingHandlerA samplingA() { ... } // @McpSampling("myClient")
@Bean SamplingHandlerB samplingB() { ... } // @McpSampling("myClient")

// after
@Bean SamplingHandler sampling() { ... } // single @McpSampling("myClient") handler

// At startup, verify exactly one @McpSampling handler per client
Map<String, Long> counts = beansWithMcpSampling.stream()
    .collect(Collectors.groupingBy(b -> b.clientName(), Collectors.counting()));
counts.forEach((client, n) -> {
    if (n > 1) throw new IllegalStateException("Multiple @McpSampling handlers for client " + client);
});

When it happens

Trigger: Registering two or more beans with @McpSampling methods targeting the same client name; the conflict surfaces during application context startup in postProcessBeanFactory.

Common situations: Multiple @Configuration classes each defining sampling handlers for the same client; leftover bean after refactoring; auto-configuration plus a manually defined handler bean colliding.

Related errors

• Found 2 elicitation handlers for client [%s], found in bean
• SSE connection '<connectionName>' requires a 'url' property.
• Failed to read stdio connection resource
• Failed to create SSE transport for connection '<connectionNa
• Multiple tools with the same name (%s)

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