spring-projects/spring-ai · error · IllegalArgumentException

clients must not be empty

Error message

clients must not be empty

What it means

The AsyncSamplingSpecification compact constructor requires a non-null clients array with at least one non-blank entry after trimming; otherwise it throws IllegalArgumentException with 'clients must not be empty'. The clients array identifies which MCP clients this sampling handler applies to, and an empty set would make the specification meaningless.

Solutions

1. Pass at least one real client name, e.g. new AsyncSamplingSpecification(new String[]{"claude-desktop"}, handler)
2. Guard the source list for emptiness before constructing the specification
3. If 'all clients' is intended, use the API's wildcard/omit-clients variant instead of an empty array

Example fix

// before
var spec = new AsyncSamplingSpecification(new String[0], handler);
// after
var spec = new AsyncSamplingSpecification(new String[]{"client-a"}, handler);

if (clients == null || clients.length == 0 || Arrays.stream(clients).map(String::trim).anyMatch(String::isEmpty)) {
    throw new IllegalArgumentException("clients must contain at least one non-blank name");
}
var spec = new AsyncSamplingSpecification(clients, handler);

try { new AsyncSamplingSpecification(clients, handler); } catch (IllegalArgumentException e) { fallbackToDefaultClients(); }

When it happens

Trigger: new AsyncSamplingSpecification(new String[0], handler) or new AsyncSamplingSpecification(new String[]{" ", ""}, handler) — empty array or only whitespace/empty strings.

Common situations: Building client filter lists from config properties that defaulted to empty; splitting an empty/blank config string into an array; passing a null-defaulted varargs call site.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• clients must not be empty
• Method must have at least 1 parameter (CreateMessageRequest)
• Anthropic Citations API requires all documents to have…
• At least one client Id must be specified
• Bean must not be null

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

Appendix: source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/sampling/AsyncSamplingSpecification.java:33

 */

package org.springframework.ai.mcp.annotation.method.sampling;

import java.util.Arrays;
import java.util.Objects;
import java.util.function.Function;

import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
import reactor.core.publisher.Mono;

public record AsyncSamplingSpecification(String[] clients,
		Function<CreateMessageRequest, Mono<CreateMessageResult>> samplingHandler) {

	public AsyncSamplingSpecification {
		Objects.requireNonNull(clients, "clients must not be null");
		if (clients.length == 0 || Arrays.stream(clients).map(String::trim).anyMatch(String::isEmpty)) {
			throw new IllegalArgumentException("clients must not be empty");
		}
		Objects.requireNonNull(samplingHandler, "samplingHandler must not be null");
	}

}

View on GitHub (pinned to 98a7beda4f)