alibaba/spring-ai-alibaba · error · IllegalArgumentException

must be at least , got

Error message

${fieldName} must be at least ${minValue}, got: ${num}

What it means

requirePositiveNumber() throws this when the numeric field is a Number but below the minimum value required by the agent type (e.g. max_iterations must be >= 1). The message shows both the required minimum and the offending value.

Solutions

1. Raise the field's value to at least the stated minimum
2. For a loop agent wanting many iterations, use a positive number like 1 or the intended bound
3. Fix upstream logic that computes the value so it cannot produce 0 or negatives

Example fix

// before
{"type": "loop_agent", "name": "looper", "max_iterations": 0}
// after
{"type": "loop_agent", "name": "looper", "max_iterations": 3}

int v = ((Number) config.get("max_iterations")).intValue();
if (v < 1) {
    throw new IllegalArgumentException("max_iterations must be >= 1, got " + v);
}

try {
    provider.validateDSL(root);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("must be at least")) {
        // read the minimum from the message and clamp/auto-fix the field
    }
}

When it happens

Trigger: ((Number) value).intValue() < minValue in requirePositiveNumber(), e.g. passing max_iterations: 0 to a LoopAgent, or a routing/parallel knob set to 0 or negative.

Common situations: Setting a loop limit to 0 intending 'unlimited'; a UI defaulting a field to 0; negative values from a buggy computation upstream.

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
• 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/49080530229bbe71. 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:110

	}

	/**
	 * 校验数值字段
	 * @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");
		}
		int num = ((Number) value).intValue();
		if (num < minValue) {
			throw new IllegalArgumentException(fieldName + " must be at least " + minValue + ", got: " + num);
		}
		return num;
	}

	/**
	 * 检查字符串是否为空
	 */
	protected boolean isBlank(String s) {
		return s == null || s.trim().isEmpty();
	}

	/**
	 * 检查是否有有效的输入键
	 */
	protected boolean hasValidInputKey(Map<String, Object> root) {
		String inputKey = (String) root.get("input_key");
		List<?> inputKeys = (List<?>) root.get("input_keys");
		return !isBlank(inputKey) || (inputKeys != null && !inputKeys.isEmpty());

View on GitHub (pinned to f82da0b50f)