alibaba/spring-ai-alibaba · error · IllegalArgumentException

Description must be provided

Error message

Description must be provided

What it means

A2aRemoteAgent.Builder.build() requires a non-blank description; the description is published in the agent's AgentCard and used for agent discovery/matching in A2A scenarios. If it is null or blank the builder throws IllegalArgumentException before any network work starts.

Source

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

		}

		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();

			return new A2aRemoteAgent(this);
		}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Add .description("<meaningful description>") to the builder chain.
2. Validate the configured description is non-blank before building.
3. Fill a placeholder description in configs where one is not authored.

Example fix

// before
A2aRemoteAgent.builder().name("agent").build();

// after
A2aRemoteAgent.builder()
    .name("agent")
    .description("Agent handling billing queries")
    .build();

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

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

When it happens

Trigger: Calling A2aRemoteAgent.builder().name("x").build() without .description(...), or with an empty/whitespace-only description.

Common situations: Minimal examples that set only name and agentCard; config files missing a description property; developers unaware the description is mandatory for card publication.

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

• Name 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/661cc37ba2022430. Report an issue: GitHub.