{"record":{"id":"befa59eee62774b8","repo":"alibaba/spring-ai-alibaba","slug":"type-requires-fieldname","errorCode":null,"errorMessage":"${type} requires '${fieldName}'","messagePattern":"(.+?) requires '(.+?)'","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"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","lineNumber":103,"sourceCode":"\t\t}\n\t\tList<Map<String, Object>> subAgents = (List<Map<String, Object>>) subs;\n\t\tif (subAgents.size() < minCount) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\ttype() + \" requires at least \" + minCount + \" sub-agent(s), got: \" + subAgents.size());\n\t\t}\n\t\treturn subAgents;\n\t}\n\n\t/**\n\t * 校验数值字段\n\t * @param value 字段值\n\t * @param fieldName 字段名\n\t * @param minValue 最小值（包含）\n\t * @return 数值\n\t */\n\tprotected int requirePositiveNumber(Object value, String fieldName, int minValue) {\n\t\tif (value == null) {\n\t\t\tthrow new IllegalArgumentException(type() + \" requires '\" + fieldName + \"'\");\n\t\t}\n\t\tif (!(value instanceof Number)) {\n\t\t\tthrow new IllegalArgumentException(fieldName + \" must be a number\");\n\t\t}\n\t\tint num = ((Number) value).intValue();\n\t\tif (num < minValue) {\n\t\t\tthrow new IllegalArgumentException(fieldName + \" must be at least \" + minValue + \", got: \" + num);\n\t\t}\n\t\treturn num;\n\t}\n\n\t/**\n\t * 检查字符串是否为空\n\t */\n\tprotected boolean isBlank(String s) {\n\t\treturn s == null || s.trim().isEmpty();\n\t}\n","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/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#L85-L121","documentation":"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.","triggerScenarios":"validateSpecific() calls requirePositiveNumber(root.get(\"someField\"), \"someField\", minValue) and the value is null because the key is missing from the config map.","commonSituations":"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.","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"],"exampleFix":"// before\n{\"type\": \"loop_agent\", \"name\": \"looper\", \"sub_agents\": [...]}\n// after\n{\"type\": \"loop_agent\", \"name\": \"looper\", \"max_iterations\": 5, \"sub_agents\": [...]}","handlingStrategy":"validation","validationCode":"for (String required : List.of(\"max_iterations\")) {\n    if (config.get(required) == null) {\n        throw new IllegalArgumentException(\"missing required numeric field: \" + required);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    provider.validateDSL(root);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().matches(\".*requires '[^']+'\")) {\n        // extract fieldName from the message and mark the field in the UI\n    }\n}","preventionTips":["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"],"tags":["validation","dsl","numeric"],"backgroundTag":"missing-required-config-field","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}