alibaba/spring-ai-alibaba · error · IllegalArgumentException

must be a number

Error message

${fieldName} must be a number

What it means

requirePositiveNumber() throws this when the field is present but is not a Number instance — e.g. a String "5", a Boolean, or a nested map. DSL values parsed from JSON/YAML can arrive as strings when quoted, and the provider does not coerce them.

Solutions

1. Remove quotes so the value is a real number in JSON/YAML
2. Convert the string to a number in upstream code before passing the config to the generator
3. Check how the DSL file is parsed — YAML typers/loose parsers may help

Example fix

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

Object v = config.get("max_iterations");
if (!(v instanceof Number)) {
    throw new IllegalArgumentException("max_iterations must be a JSON/YAML number, not " + (v == null ? "null" : v.getClass().getSimpleName()));
}

static Integer asInt(Object v) {
    return (v instanceof Number n) ? n.intValue() : null;
}

try {
    provider.validateDSL(root);
} catch (IllegalArgumentException e) {
    if (e.getMessage().endsWith("must be a number")) {
        // show the offending field and its quoted/string value
    }
}

When it happens

Trigger: root.get(fieldName) returns a String like "3" (quoted number in YAML/JSON) or any non-numeric object, and validateSpecific() passes it to requirePositiveNumber().

Common situations: Quoting numbers in YAML (iterations: "5") which YAML parses as a string; JSON generated by a form UI that stringifies all values; reading config from an env var or DB column typed as text.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• invalid agent dsl: missing 'agent' object or flat agent…
• invalid agent dsl: 'type/agent_class' and 'name' are…
• invalid dify dsl
• invalid dsl
• ReactAgent requires model configuration in handle

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

			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");
		}
		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();
	}

	/**
	 * 检查是否有有效的输入键
	 */

View on GitHub (pinned to f82da0b50f)