What causes "${type} requires '${fieldName}'" in alibaba/spring-ai-alibaba?

Set the named field to a numeric value >= the documented minimum

alibaba/spring-ai-alibaba · error · IllegalArgumentException

requires

Error message

${type} requires '${fieldName}'

What it means

requirePositiveNumber() throws this when the checked numeric field is null (absent) in the DSL config. Fields validated this way (e.g. loop iteration limits, timeouts) are mandatory for the agent type to generate correct code. The message names the missing field and is prefixed by the agent type.

Solutions

Set the named field to a numeric value >= the documented minimum
Check which agent type the message prefixes and its docs for the required field and minimum
If the field should be optional, give it an explicit default in the config

Example fix

// before
{"type": "loop_agent", "name": "looper", "sub_agents": [...]}
// after
{"type": "loop_agent", "name": "looper", "max_iterations": 5, "sub_agents": [...]}

Defensive patterns

Strategy: validation

Validate before calling

for (String required : List.of("max_iterations")) {
    if (config.get(required) == null) {
        throw new IllegalArgumentException("missing required numeric field: " + required);
    }
}

Try / catch

try {
    provider.validateDSL(root);
} catch (IllegalArgumentException e) {
    if (e.getMessage().matches(".*requires '[^']+'")) {
        // extract fieldName from the message and mark the field in the UI
    }
}

Prevention

Consult the agent type's docs for required numeric knobs
Provide explicit defaults in templates instead of omitting fields
Diff configs against a known-good example when upgrading DSL versions

When it happens

Trigger: validateSpecific() calls requirePositiveNumber(root.get("someField"), "someField", minValue) and the value is null because the key is missing from the config map.

Common situations: Omitting "max_iterations" on a loop agent or a similar required numeric knob; a template/export that drops default values; key renamed between DSL versions.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

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