alibaba/spring-ai-alibaba · error · IllegalArgumentException

Agent name must not be empty

Error message

Agent name must not be empty

What it means

DefaultBuilder.build() validates that the agent name is non-empty (StringUtils.hasText) and throws IllegalArgumentException before constructing the ReactAgent. Every agent requires a name used for graph node naming and hooks.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/DefaultBuilder.java:59

import java.lang.reflect.Field;
import java.lang.reflect.Method;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

public class DefaultBuilder extends Builder {

	private static final Logger logger = LoggerFactory.getLogger(DefaultBuilder.class);

	public static final String POSSIBLE_LLM_TOOL_NAME_CHANGE_WARNING
				= "LLM may have adapted the tool name '{}', especially if the name was truncated due to length limits. If this is the case, you can customize the prefixing and processing logic using McpToolNamePrefixGenerator";

	@Override
	public ReactAgent build() {

		// Validate name is not empty
		if (!StringUtils.hasText(this.name)) {
			throw new IllegalArgumentException("Agent name must not be empty");
		}

		// Validate either chatClient or model is provided
		if (chatClient == null && model == null) {
			throw new IllegalArgumentException("Either chatClient or model must be provided");
		}

		// Get source options from ChatClient (when provided) or from ChatModel (when building from model).
		ChatOptions sourceOptions = (chatClient != null)
				? getChatClientDefaultOptions(chatClient)
				: getChatModelDefaultOptions(model);
		ChatOptions effectiveOptions = mergeSourceOptionsWithAgentOptions(sourceOptions, this.chatOptions);

		if (chatClient == null) {
			ChatClient.Builder clientBuilder = ChatClient.builder(model,
					this.observationRegistry == null ? ObservationRegistry.NOOP : this.observationRegistry,
					this.customObservationConvention, this.advisorObservationConvention);
			if (effectiveOptions != null) {

View on GitHub (pinned to f82da0b50f)

Solutions

1. Call .name("my-agent") with a non-blank string on the builder before build().
2. Validate the configured name early (fail fast at startup) before reaching build().
3. If the name comes from config, provide a default or check hasText beforehand.

Example fix

// before
ReactAgent agent = ReactAgent.builder().model(model).build();
// after
ReactAgent agent = ReactAgent.builder().name("research-agent").model(model).build();

if (agentName == null || agentName.isBlank()) throw new IllegalArgumentException("Agent name must be a non-blank string before build()");

try { agent = builder.build(); } catch (IllegalArgumentException e) { throw new IllegalStateException("Agent misconfigured: " + e.getMessage(), e); }

When it happens

Trigger: Calling ReactAgent.builder().build() without ever calling .name(...), or with name(null)/name("")/name(" ").

Common situations: Copy-pasting a builder chain and dropping the name() line; loading agent name from config that is missing or blank.

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

• maxParallelTools must be at least 1
• Either chatClient or model must be provided
• Tool not found with id: <id>
• Unknown agent status code:
• Unknown agent type code:

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