alibaba/spring-ai-alibaba · error · IllegalArgumentException

ReactAgent tool names cannot be empty

Error message

ReactAgent tool names cannot be empty

What it means

ReactAgentProvider.validateSpecific validates a ReactAgent node definition during project generation. If the agent declares a tools list and any entry is a string that is empty or whitespace-only, generation is aborted with this IllegalArgumentException. It exists to prevent generating an agent whose tool bindings contain meaningless empty names.

Solutions

1. Open the agent node config and remove or fill in every empty string entry in the tools list.
2. Trim and filter the tools list client-side before saving the workflow definition.
3. Wrap generation in a try-catch for IllegalArgumentException and surface a per-field validation message for the tools input.

Example fix

// before
tools: ["", "web-search"]
// after
tools: ["web-search"]  // remove empty names; validate before submit

List<String> tools = (List<String>) handle.getOrDefault("tools", List.of());
if (tools.stream().anyMatch(t -> t == null || t.trim().isEmpty()))
    throw new IllegalArgumentException("ReactAgent has empty tool names");

boolean validTools(Object tools) { return !(tools instanceof List<?> l) || l.stream().allMatch(t -> t instanceof String s && !s.trim().isEmpty()); }

try { generator.generate(...); } catch (IllegalArgumentException e) { log.error("Invalid agent config: {}", e.getMessage()); }

When it happens

Trigger: Calling generate() on a project whose metadata contains a ReactAgent node with a 'tools' array (non-empty) where at least one element is a String whose trim() is empty, e.g. tools: ["", " ", "search"].

Common situations: A user left a blank row in the tools UI field; YAML/JSON config authored by hand with an empty quoted string; a form submitted without selecting tools but the list already contains a placeholder empty entry.

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

• key cannot be empty
• Agent name must not be empty
• AgentCard or AgentCardProvider must be provided
• AgentScope Model must be provided for AgentScope routing…
• AgentScope routing flow requires at least one sub-agent

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

Appendix: source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/builder/generator/service/generator/agent/impl/ReactAgentProvider.java:173

			.var(var)
			.resolver(hasResolver);
	}

	@Override
	protected void validateSpecific(Map<String, Object> root) {
		// ReactAgent 必须有 model 配置
		Map<String, Object> handle = requireHandle(root);

		if (handle.get("model") == null) {
			throw new IllegalArgumentException("ReactAgent requires model configuration in handle");
		}

		// 如果有 tools，检查相关配置
		if (handle.get("tools") instanceof List<?> tools && !tools.isEmpty()) {
			// 检查 tools 是否为空字符串
			for (Object tool : tools) {
				if (tool instanceof String s && s.trim().isEmpty()) {
					throw new IllegalArgumentException("ReactAgent tool names cannot be empty");
				}
			}
		}

		// 检查 max_iterations 如果存在，必须是正数
		Object maxIterations = handle.get("max_iterations");
		if (maxIterations != null) {
			requirePositiveNumber(maxIterations, "max_iterations", 1);
		}
	}

}

View on GitHub (pinned to f82da0b50f)