alibaba/spring-ai-alibaba · error · IllegalArgumentException

Name must be provided

Error message

Name must be provided

What it means

A2aRemoteAgent.Builder.build() validates that a non-blank name was set before constructing the agent; a remote A2A agent must have a name so it can be addressed and, when using an AgentCardProvider that resolves by name, matched to its AgentCard. This is a fail-fast IllegalArgumentException at construction time.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/a2a/A2aRemoteAgent.java:217

		public Builder compileConfig(CompileConfig compileConfig) {
			this.compileConfig = compileConfig;
			return this;
		}

		public Builder streaming(boolean streaming) {
			this.streaming = streaming;
			return this;
		}

		public Builder shareState(boolean shareState) {
			this.shareState = shareState;
			return this;
		}

		public A2aRemoteAgent build() {
			// Validation
			if (name == null || name.trim().isEmpty()) {
				throw new IllegalArgumentException("Name must be provided");
			}
			if (description == null || description.trim().isEmpty()) {
				throw new IllegalArgumentException("Description must be provided");
			}
			if (agentCard == null) {
				if (null == agentCardProvider) {
					throw new IllegalArgumentException("AgentCard or AgentCardProvider must be provided");
				}
				if (agentCardProvider.supportGetAgentCardByName()) {
					agentCard = agentCardProvider.getAgentCard(name);
				}
				else {
					agentCard = agentCardProvider.getAgentCard();
				}
			}

			this.streaming = agentCard.capabilities().streaming();

View on GitHub (pinned to f82da0b50f)

Solutions

1. Set a name: A2aRemoteAgent.builder().name("my-remote-agent").description("...")...build().
2. Validate the config value is non-blank before invoking the builder.
3. Default to a sensible name derived from context (e.g. the target service id) when the input is blank.

Example fix

// before
A2aRemoteAgent agent = A2aRemoteAgent.builder()
    .description("Remote agent")
    .build(); // IllegalArgumentException

// after
A2aRemoteAgent agent = A2aRemoteAgent.builder()
    .name("my-remote-agent")
    .description("Remote agent")
    .build();

if (name == null || name.isBlank()) {
    throw new IllegalArgumentException("name must be non-blank before building A2aRemoteAgent");
}

try {
    A2aRemoteAgent a = builder.build();
} catch (IllegalArgumentException e) {
    log.error("Builder validation failed: {}", e.getMessage());
}

When it happens

Trigger: Calling A2aRemoteAgent.builder().build() without calling .name(...), or with .name("") or a whitespace-only string.

Common situations: Building agents programmatically from config where the name field is missing/empty; copy-pasting a builder snippet and forgetting the name() call; a null property loaded from application config.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Description must be provided
• AgentCard or AgentCardProvider must be provided
• Name must be provided
• ParallelAgent requires at least 2 sub-agents for parallel ex
• Name must be provided

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/4564249350de58a3. Report an issue: GitHub.