spring-projects/spring-ai · error · IllegalArgumentException

clients must not be empty

Error message

clients must not be empty

What it means

The SyncSamplingSpecification compact constructor requires a non-null clients array containing at least one non-blank entry; empty arrays or arrays of blank strings throw IllegalArgumentException with 'clients must not be empty'. The clients array names the MCP clients this sync sampling handler serves.

Solutions

1. Provide at least one concrete client name in the array
2. Validate the originating config/property list for emptiness before constructing the specification
3. Use the framework's mechanism for 'apply to all clients' rather than passing an empty array

Example fix

// before
var spec = new SyncSamplingSpecification(split(cfg), handler); // split -> []
// after
String[] clients = split(cfg);
if (clients.length == 0) { clients = new String[]{"default-client"}; }
var spec = new SyncSamplingSpecification(clients, 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 SyncSamplingSpecification(clients, handler);

try { new SyncSamplingSpecification(clients, handler); } catch (IllegalArgumentException e) { applyDefaultClientList(); }

When it happens

Trigger: new SyncSamplingSpecification(new String[0], handler) or with entries like new String[]{""} or new String[]{" "} — empty or whitespace-only client names.

Common situations: Client lists sourced from empty properties/env config; string split producing an empty array; copy-pasted specification code where the client list was never filled in.

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/23f5992e2c85a9b1. Report an issue: GitHub.

Appendix: source

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

 * limitations under the License.
 */

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;

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

	public SyncSamplingSpecification {
		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)