spring-projects/spring-ai · error · IllegalArgumentException

clients must not be empty

Error message

clients must not be empty

What it means

The compact constructor of the SyncToolListChangedSpecification record validates its inputs: clients must be non-null, non-empty after trimming, and contain no blank entries; toolListChangeHandler must be non-null. A clients array that is null/empty or contains only whitespace triggers this IllegalArgumentException.

Source

Thrown at mcp/mcp-annotations/src/main/java/org/springframework/ai/mcp/annotation/method/changed/tool/SyncToolListChangedSpecification.java:31

 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

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

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

import io.modelcontextprotocol.spec.McpSchema;

public record SyncToolListChangedSpecification(String[] clients, Consumer<List<McpSchema.Tool>> toolListChangeHandler) {

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

}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Pass at least one non-blank client name, e.g. new SyncToolListChangedSpecification(new String[]{"myClient"}, handler).
2. Trim/verify client names programmatically before constructing the specification.
3. Fix the @McpToolListChanged(clients = ...) attribute to list the actual MCP client/connection names.

Example fix

// before
new SyncToolListChangedSpecification(new String[]{""}, handler); // throws
// after
new SyncToolListChangedSpecification(new String[]{"client1"}, handler);

String[] clients = ...; // from config/annotation
if (clients == null || Arrays.stream(clients).map(String::trim).allMatch(String::isEmpty)) {
    throw new IllegalStateException("at least one non-blank client name required");
}

try {
    var spec = new SyncToolListChangedSpecification(clients, handler);
} catch (IllegalArgumentException e) {
    LOG.error("invalid clients for tool-list-changed spec: {}", e.getMessage());
}

When it happens

Trigger: Creating SyncToolListChangedSpecification with new String[0], with a clients array containing empty or whitespace-only strings, or calling annotation-processor registration where the @McpToolListChanged clients attribute resolves to nothing.

Common situations: Omitting the clients attribute on the annotation so it defaults to an empty array; building client names dynamically and producing blank strings; typo leaving the array unfilled.

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

• 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() + "
• clients must not be empty
• clients must not be empty

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