spring-projects/spring-ai · error · IllegalArgumentException

At least one client Id must be specified

Error message

At least one client Id must be specified

What it means

IllegalArgumentException thrown in the compact constructor of the SyncPromptListChangedSpecification record when the clients array is non-null but has length 0. Each specification must target at least one MCP client Id for the sync prompt-list-changed handler; an empty array would bind the handler to nothing and is treated as invalid configuration.

Source

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

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

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

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

import io.modelcontextprotocol.spec.McpSchema;

public record SyncPromptListChangedSpecification(String[] clients,
		Consumer<List<McpSchema.Prompt>> promptListChangeHandler) {

	public SyncPromptListChangedSpecification {
		Objects.requireNonNull(clients, "clients must not be null");
		if (clients.length == 0) {
			throw new IllegalArgumentException("At least one client Id must be specified");
		}
		Objects.requireNonNull(promptListChangeHandler, "promptListChangeHandler must not be null");
	}

}

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Supply at least one valid client Id, e.g. new SyncPromptListChangedSpecification(new String[]{"myClient"}, handler).
2. Validate configured client Ids are non-empty before constructing the record and raise a clear configuration error.
3. Ensure the Ids match the names of registered McpSyncClient beans/connections.

Example fix

// before
new SyncPromptListChangedSpecification(new String[0], this::onPromptsChanged);
// after
new SyncPromptListChangedSpecification(new String[]{"client1"}, this::onPromptsChanged);

if (clients == null || clients.length == 0) {
    throw new IllegalStateException("At least one MCP client Id must be configured for SyncPromptListChangedSpecification");
}
new SyncPromptListChangedSpecification(clients, handler);

try {
    new SyncPromptListChangedSpecification(clients, handler);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("At least one client Id")) {
        throw new ConfigurationException("Configure at least one MCP client Id for the sync prompt list changed handler", e);
    }
    throw e;
}

When it happens

Trigger: new SyncPromptListChangedSpecification(new String[0], consumer) or an empty array produced dynamically from config/properties. The companion checks also require clients != null and handler != null.

Common situations: Empty property lists for client Ids; a filter step removing all candidate clients; renaming McpSyncClient beans so the collected Id list no longer matches and effectively ends up empty; scaffolded specs left with placeholder empty arrays.

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

• At least one client Id must be specified
• At least one client Id must be specified
• Failed to read stdio connection resource
• SSE connection '<connectionName>' requires a 'url' property.
• Failed to create SSE transport for connection '<connectionNa

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