{"record":{"id":"ab63685f2329efae","repo":"alibaba/spring-ai-alibaba","slug":"subagent-name-is-required","errorCode":null,"errorMessage":"SubAgent name is required","messagePattern":"SubAgent name is required","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/extension/interceptor/SubAgentSpec.java","lineNumber":153,"sourceCode":"\t\t}\n\n\t\t/**\n\t\t * Set custom interceptors for this subagent.\n\t\t * These will be applied after the default interceptors from SubAgentInterceptor.\n\t\t */\n\t\tpublic Builder interceptors(List<ModelInterceptor> interceptors) {\n\t\t\tthis.interceptors = interceptors;\n\t\t\treturn this;\n\t\t}\n\n\t\tpublic Builder enableLoopingLog(boolean enableLoopingLog) {\n\t\t\tthis.enableLoopingLog = enableLoopingLog;\n\t\t\treturn this;\n\t\t}\n\n\t\tpublic SubAgentSpec build() {\n\t\t\tif (name == null || name.trim().isEmpty()) {\n\t\t\t\tthrow new IllegalArgumentException(\"SubAgent name is required\");\n\t\t\t}\n\t\t\tif (description == null || description.trim().isEmpty()) {\n\t\t\t\tthrow new IllegalArgumentException(\"SubAgent description is required\");\n\t\t\t}\n\t\t\tif (systemPrompt == null || systemPrompt.trim().isEmpty()) {\n\t\t\t\tthrow new IllegalArgumentException(\"SubAgent system prompt is required\");\n\t\t\t}\n\t\t\treturn new SubAgentSpec(this);\n\t\t}\n\t}\n}\n\n","sourceCodeStart":135,"sourceCodeEnd":166,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/extension/interceptor/SubAgentSpec.java#L135-L166","documentation":"SubAgentSpec's builder requires a non-null, non-blank name before it can produce a spec. The framework uses the name to identify the sub-agent when the orchestrating agent delegates work to it, so building without one would yield an unusable spec. This IllegalArgumentException is thrown from build() as a fail-fast validation.","triggerScenarios":"Calling SubAgentSpec.builder()...build() without invoking name(String), or invoking it with null, \"\", or a whitespace-only string.","commonSituations":"Assembling sub-agents programmatically from config where the name field is optional/absent; forgetting the fluent name() call when copying an example; dynamically generated specs from a model or YAML mapping that omits 'name'.","solutions":["Add a name(...) call to the SubAgentSpec builder chain before build().","If the name comes from external config, validate it is non-blank before building and provide a default or fail with a clear message.","If the spec is optional in your flow, skip building it entirely rather than building with a blank name."],"exampleFix":"// before\nSubAgentSpec spec = SubAgentSpec.builder()\n    .description(\"Handles billing questions\")\n    .systemPrompt(\"You are a billing agent\")\n    .build();\n// after\nSubAgentSpec spec = SubAgentSpec.builder()\n    .name(\"billing-agent\")\n    .description(\"Handles billing questions\")\n    .systemPrompt(\"You are a billing agent\")\n    .build();","handlingStrategy":"validation","validationCode":"if (name == null || name.trim().isEmpty()) {\n    throw new IllegalArgumentException(\"Cannot build SubAgentSpec: name is required\");\n}\nSubAgentSpec spec = SubAgentSpec.builder().name(name)...build();","typeGuard":"static boolean hasText(String s) { return s != null && !s.trim().isEmpty(); }","tryCatchPattern":"try {\n    spec = SubAgentSpec.builder()...build();\n} catch (IllegalArgumentException e) {\n    log.error(\"Invalid SubAgentSpec: {}\", e.getMessage());\n}","preventionTips":["Always call name(), description(), and systemPrompt() together as a group when building SubAgentSpec.","Centralize spec construction in one factory method so required fields are never skipped.","Load names from config with non-blank validation at startup."],"tags":["java","builder-validation","subagent"],"backgroundTag":"missing-required-argument","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}