alibaba/spring-ai-alibaba · error · IllegalArgumentException

requires at least sub-agent(s), got

Error message

${type} requires at least ${minCount} sub-agent(s), got: ${size}

What it means

requireSubAgents() throws this when "sub_agents" is an array but contains fewer entries than the agent type's required minimum (minCount). Each composition pattern has semantic minimums, e.g. RoutingAgent needs at least 2 sub-agents to route between. The actual size is included in the message.

Solutions

1. Add more sub-agent definitions to the "sub_agents" array until it meets the minimum for the agent type
2. If fewer agents are genuinely needed, switch to a single-agent type like react_agent
3. Read the message's 'got: N' count to see how many more are required

Example fix

// before
{"type": "routing_agent", "name": "router", "sub_agents": [onlyOneAgent]}
// after
{"type": "routing_agent", "name": "router", "sub_agents": [agentA, agentB]}

int min = 2; // e.g. RoutingAgent minimum
List<?> subs = (List<?>) config.get("sub_agents");
if (subs == null || subs.size() < min) {
    throw new IllegalArgumentException(type + " needs at least " + min + " sub_agents");
}

try {
    provider.validateDSL(root);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("at least") && e.getMessage().contains("sub-agent")) {
        // parse the required minimum from the message and prompt the user
    }
}

When it happens

Trigger: A provider calls requireSubAgents(root, minCount) and the sub_agents list is non-null and is a List but subAgents.size() < minCount, e.g. RoutingAgent with only 1 sub-agent when 2 are required.

Common situations: Removing an agent from a pipeline and forgetting the minimum; copy-pasting a single-agent example for a routing agent; a migration script that drops empty sub-agent entries.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• requires 'sub_agents' (array)
• must be a number
• invalid agent dsl: missing 'agent' object or flat agent…
• invalid agent dsl: 'type/agent_class' and 'name' are…
• invalid dify dsl

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/c6555a4f169eab41. 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/AbstractAgentTypeProvider.java:88

			handle = new HashMap<>();
		}
		return handle;
	}

	/**
	 * 校验必须有子代理
	 * @param root DSL 根对象
	 * @param minCount 最小数量
	 */
	@SuppressWarnings("unchecked")
	protected List<Map<String, Object>> requireSubAgents(Map<String, Object> root, int minCount) {
		Object subs = root.get("sub_agents");
		if (!(subs instanceof List)) {
			throw new IllegalArgumentException(type() + " requires 'sub_agents' (array)");
		}
		List<Map<String, Object>> subAgents = (List<Map<String, Object>>) subs;
		if (subAgents.size() < minCount) {
			throw new IllegalArgumentException(
					type() + " requires at least " + minCount + " sub-agent(s), got: " + subAgents.size());
		}
		return subAgents;
	}

	/**
	 * 校验数值字段
	 * @param value 字段值
	 * @param fieldName 字段名
	 * @param minValue 最小值（包含）
	 * @return 数值
	 */
	protected int requirePositiveNumber(Object value, String fieldName, int minValue) {
		if (value == null) {
			throw new IllegalArgumentException(type() + " requires '" + fieldName + "'");
		}
		if (!(value instanceof Number)) {
			throw new IllegalArgumentException(fieldName + " must be a number");

View on GitHub (pinned to f82da0b50f)