alibaba/spring-ai-alibaba · error · IllegalArgumentException

Name must be provided

Error message

Name must be provided

What it means

FlowAgentBuilder.validate() throws when the builder name is null or blank before any flow agent (sequential, parallel, routing, etc.) is created. The name identifies the agent node in the graph and is mandatory for all flow agents.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/builder/FlowAgentBuilder.java:177

		this.hooks.addAll(hooks);
		return self();
	}

	/**
	 * Returns the concrete builder instance. This method enables fluent interface support
	 * in subclasses.
	 * @return this builder instance
	 */
	protected abstract B self();

	/**
	 * Validates the builder state before creating the agent. Subclasses can override this
	 * method to add specific validation logic.
	 * @throws IllegalArgumentException if validation fails
	 */
	protected void validate() {
		if (name == null || name.trim().isEmpty()) {
			throw new IllegalArgumentException("Name must be provided");
		}
		if (subAgents == null || subAgents.isEmpty()) {
			throw new IllegalArgumentException("At least one sub-agent must be provided for flow");
		}
	}

	/**
	 * Builds the concrete FlowAgent instance. Subclasses must implement this method to
	 * create the specific agent type.
	 * @return the built FlowAgent instance
	 * @throws GraphStateException if agent creation fails
	 */
	public T build() {
		if (this.saver != null) {
			if (this.compileConfig == null) {
				this.compileConfig = CompileConfig.builder().saverConfig(SaverConfig.builder().register(saver).build()).build();
			}
			this.compileConfig = CompileConfig.builder(compileConfig).saverConfig(SaverConfig.builder().register(saver).build()).build();

View on GitHub (pinned to f82da0b50f)

Solutions

1. Call .name("<agent-name>") before .build()
2. Check that the config/property feeding the name is set and non-blank
3. Validate/trim the name string before passing it to the builder

Example fix

// before
SequentialAgent.builder().subAgents(a, b).build();
// after
SequentialAgent.builder().name("pipeline").subAgents(a, b).build();

if (name == null || name.trim().isEmpty()) throw new IllegalArgumentException("Flow agent name required");

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

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

When it happens

Trigger: Calling any FlowAgentBuilder subclass's build() without .name(...), or with a whitespace-only name.

Common situations: Name supplied from a nullable config value; builder assembled dynamically and the name setter skipped; migration from an API version where name was optional.

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/e0d7a617d2677e68. Report an issue: GitHub.