spring-projects/spring-ai · error

clients must not be empty

Error message

clients must not be empty

What it means

The compact constructor of SyncResourceListChangedSpecification validates that the `clients` array is non-null and contains no null/blank entries. The library requires at least one named MCP client so the resource-list-changed specification can be registered against a concrete client connection; an empty array would silently produce a no-op subscription.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/changed/resource/SyncResourceListChangedSpecification.java:32

 * limitations under the License.
 */

package org.springframework.ai.mcp.annotation.method.changed.resource;

import java.util.Arrays;
import java.util.List;
import java.util.Objects;
import java.util.function.Consumer;

import io.modelcontextprotocol.spec.McpSchema;

public record SyncResourceListChangedSpecification(String[] clients,
		Consumer<List<McpSchema.Resource>> resourceListChangeHandler) {

	public SyncResourceListChangedSpecification {
		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(resourceListChangeHandler, "resourceListChangeHandler must not be null");
	}

}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Pass at least one valid MCP client name in the clients array, e.g. new SyncResourceListChangedSpecification(new String[]{"client1"}, handler)
2. Check the source of the client names (properties/env/config bean) and verify it is populated and non-empty before constructing the specification
3. Trim and filter the candidate names before passing them, and fail fast with a clear message if the filtered list is empty

Example fix

// before
SyncResourceListChangedSpecification spec = new SyncResourceListChangedSpecification(
    config.getClients().split(","), handler); // throws when config value is empty
// after
String[] clients = java.util.Arrays.stream(config.getClients().split(","))
    .map(String::trim).filter(s -> !s.isEmpty()).toArray(String[]::new);
if (clients.length == 0) throw new IllegalStateException("No MCP clients configured");
SyncResourceListChangedSpecification spec = new SyncResourceListChangedSpecification(clients, handler);

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

static boolean validClients(String[] clients) { return clients != null && clients.length > 0 && java.util.Arrays.stream(clients).noneMatch(c -> c == null || c.trim().isEmpty()); }

try { new SyncResourceListChangedSpecification(clients, handler); } catch (IllegalArgumentException e) { log.error("Bad clients argument: {}", e.getMessage()); }

When it happens

Trigger: Calling the annotation-processing registration path with new SyncResourceListChangedSpecification(new String[0], handler), or passing an array whose entries are all null/whitespace strings (e.g. new String[]{""} or new String[]{" "}) — both hit `clients.length == 0` or the anyMatch(String::isEmpty) check and throw IllegalArgumentException.

Common situations: Spring configuration mistakes where client names are read from properties (e.g. a property like @mcp.clients that is empty or unset), splitting an empty string producing [""], or refactoring code so the clients array is no longer populated before building the specification.

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 exactly 1 parameter (List<McpSchema.Resourc
• Method must have void or Mono<Void> return type:
• Method must have void return type: " + method.getName() + "
• Method must have void return type:

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