spring-projects/spring-ai · warning

Multiple sampling methods found: <count>

Error message

Multiple sampling methods found: <count>

What it means

SyncMcpSamplingProvider.getSamplingSpecifications logs 'Multiple sampling methods found: N' when more than one @McpSampling-annotated method is found in the configured objects. Because MCP sampling typically maps to a single handler per provider, multiple handlers can be ambiguous and only part of them may be honored downstream.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/provider/sampling/SyncMcpSamplingProvider.java:116

					Function<CreateMessageRequest, CreateMessageResult> methodCallback = SyncMcpSamplingMethodCallback
						.builder()
						.method(mcpSamplingMethod)
						.bean(samplingObject)
						.sampling(samplingAnnotation)
						.build();

					return new SyncSamplingSpecification(samplingAnnotation.clients(), methodCallback);
				})
				.toList())
			.flatMap(List::stream)
			.toList();

		if (samplingHandlers.isEmpty()) {
			logger.warn("No sampling methods found");
		}
		if (samplingHandlers.size() > 1) {
			if (logger.isWarnEnabled()) {
				logger.warn("Multiple sampling methods found: " + samplingHandlers.size());
			}
		}

		return samplingHandlers;
	}

	/**
	 * Returns the methods of the given bean class.
	 * @param bean the bean instance
	 * @return the methods of the bean class
	 */
	protected Method[] doGetClassMethods(Object bean) {
		return bean.getClass().getDeclaredMethods();
	}

}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Consolidate to a single @McpSampling-annotated method across the registered objects.
2. Delete or de-annotate duplicate sampling methods.
3. If multiple handlers are deliberate, register them through separate providers or verify the server layer supports multiple.

Example fix

// before
@McpSampling String a(...) {...}
@McpSampling String b(...) {...}
// after
@McpSampling String handle(...) { /* dispatch internally if needed */ }

// Detect duplicates before building the sync provider:
List<Method> handlers = Arrays.stream(samplingObjects)
    .flatMap(o -> Arrays.stream(o.getClass().getDeclaredMethods()))
    .filter(m -> m.isAnnotationPresent(McpSampling.class))
    .toList();
if (handlers.size() > 1) throw new IllegalStateException("Multiple @McpSampling methods: " + handlers);

When it happens

Trigger: samplingHandlers.size() > 1 after scanning the objects passed to SyncMcpSamplingProvider — i.e. two or more public @McpSampling methods exist — triggering the warn at SyncMcpSamplingProvider.java:116.

Common situations: Duplicate handler methods after copy-paste; multiple sampling beans aggregated into one provider; leftover experimental sampling method still annotated.

Related errors

• Multiple sampling methods found: <count>
• No sampling methods found
• No sampling methods found
• Sampling not supported by the client:
• Method must have at least 1 parameter (CreateMessageRequest)

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