alibaba/spring-ai-alibaba · error · IllegalArgumentException

Name must be provided

Error message

Name must be provided

What it means

ParallelAgent.Builder.validate() throws this before building when the agent name is null or blank. Every flow agent must have a name, since it is used as the node identifier in the compiled graph. This is a fail-fast guard in the builder phase, not a runtime condition.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/ParallelAgent.java:238

		/**
		 * Returns the concrete builder instance for fluent interface support.
		 * @return this builder instance
		 */
		@Override
		protected ParallelAgentBuilder self() {
			return this;
		}

		/**
		 * Validates the builder state before creating the agent.
		 * @throws IllegalArgumentException if validation fails
		 */
		@Override
		protected void validate() {
			// Validate name first (from parent)
			if (name == null || name.trim().isEmpty()) {
				throw new IllegalArgumentException("Name must be provided");
			}

			// Validate minimum sub-agent count for ParallelAgent (skip parent subAgents
			// check)
			if (subAgents == null || subAgents.size() < 2) {
				throw new IllegalArgumentException(
						"ParallelAgent requires at least 2 sub-agents for parallel execution, but got: "
								+ (subAgents != null ? subAgents.size() : 0));
			}

			// Validate maximum sub-agent count for performance reasons
			if (subAgents.size() > 10) {
				throw new IllegalArgumentException(
						"ParallelAgent supports maximum 10 sub-agents for performance reasons, but got: "
								+ subAgents.size());
			}

			// Validate that sub-agents have unique output keys to avoid conflicts during

View on GitHub (pinned to f82da0b50f)

Solutions

1. Call .name("<unique-agent-name>") on the builder before .build()
2. Ensure the value source (config/env) actually supplies a non-blank name
3. If the name is dynamic, trim and check it before invoking the builder

Example fix

// before
ParallelAgent.builder().subAgents(a, b).build();
// after
ParallelAgent.builder().name("parallel-worker").subAgents(a, b).build();

if (name == null || name.trim().isEmpty()) throw new IllegalArgumentException("Agent name required before build()");

boolean hasName(String s) { return s != null && !s.isBlank(); }

try { agent = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("Name must be provided")) { /* set name and rebuild */ } else throw e; }

When it happens

Trigger: Calling ParallelAgent.builder() ... .build() without calling .name("...") first, or passing a name of only whitespace (e.g. .name(" ")).

Common situations: Programmatic agent construction where the name comes from a nullable config property or is accidentally set after build(); copy-pasting a builder and forgetting the name line.

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

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

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