What causes "Sampling not supported" in spring-projects/spring-ai?

Register exactly one @McpSampling handler bean for the client so samplingHandlers contains an entry under that client's name.

spring-projects/spring-ai · error · McpError

METHOD_NOT_FOUND

METHOD_NOT_FOUND

Error message

Sampling not supported

What it means

ClientMcpSyncHandlersRegistry.handleSampling is invoked when the MCP server sends a sampling request to the client. If no sampling handler is registered for the requested client name (samplingHandlers.get(name) == null), the client has no sampling capability, so it responds with an McpError carrying JSON-RPC error code METHOD_NOT_FOUND (-32601) and message "Sampling not supported".

Solutions

Register exactly one @McpSampling handler bean for the client so samplingHandlers contains an entry under that client's name.
Verify the client name used when registering the handler matches the name the server uses to address this client.
If sampling is intentionally unsupported, the error is expected — have the server handle the METHOD_NOT_FOUND sampling response gracefully or not request sampling.

Example fix

// before: no sampling handler registered for client "myClient"
// after
@Bean
SamplingHandler mySamplingHandler() {
    return new SamplingHandler(); // method annotated @McpSampling("myClient")
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Ensure a sampling handler is registered before connecting the client
if (!registry.hasSamplingHandler(clientName)) {
    throw new IllegalStateException("No @McpSampling handler registered for client " + clientName);
}

Try / catch

try {
    server.samplingRequest(...);
} catch (McpError e) {
    if (e.getJsonRpcError() != null && e.getJsonRpcError().code() == McpSchema.ErrorCodes.METHOD_NOT_FOUND) {
        // client has no sampling capability — degrade or skip
    } else {
        throw e;
    }
}

Prevention

Register an @McpSampling handler for every client that servers may sample through.
Match handler client names exactly to client identifiers.
Advertise sampling capability only when a handler exists.

When it happens

Trigger: A server initiates sampling/createMessage against a client that (a) declared no @McpSampling handler bean, or (b) declared it for a different client name, so samplingHandlers has no entry under the requested name.

Common situations: Server asks an LLM via client sampling but the client app never registered sampling support; multi-client setups where the handler is bound to client "a" but the request arrives for client "b"; handler bean not scanned/not registered in the registry.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

	public McpSchema.ClientCapabilities getCapabilities(String clientName) {
		return this.capabilitiesPerClient.getOrDefault(clientName, EMPTY_CAPABILITIES);
	}

	/**
	 * Invoke the sampling handler for a given MCP client.
	 *
	 * @see McpSampling
	 */
	public McpSchema.CreateMessageResult handleSampling(String name, McpSchema.CreateMessageRequest samplingRequest) {
		if (logger.isDebugEnabled()) {
			logger.debug("Handling sampling request for client " + name);
		}

		var handler = this.samplingHandlers.get(name);
		if (handler != null) {
			return handler.apply(samplingRequest);
		}
		throw new McpError(new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.METHOD_NOT_FOUND,
				"Sampling not supported", Map.of("reason", "Client does not have sampling capability")));
	}

	/**
	 * Invoke the elicitation handler for a given MCP client.
	 *
	 * @see McpElicitation
	 */
	public McpSchema.ElicitResult handleElicitation(String name, McpSchema.ElicitRequest elicitationRequest) {
		if (logger.isDebugEnabled()) {
			logger.debug("Handling elicitation request for client " + name);
		}

		var handler = this.elicitationHandlers.get(name);
		if (handler != null) {
			return handler.apply(elicitationRequest);
		}
		throw new McpError(new McpSchema.JSONRPCResponse.JSONRPCError(McpSchema.ErrorCodes.METHOD_NOT_FOUND,

View on GitHub (pinned to 98a7beda4f)