{"record":{"id":"32dc16c81eb77980","repo":"alibaba/spring-ai-alibaba","slug":"subagent-system-prompt-is-required","errorCode":null,"errorMessage":"SubAgent system prompt is required","messagePattern":"SubAgent system prompt 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":159,"sourceCode":"\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":141,"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#L141-L166","documentation":"SubAgentSpec's builder requires a non-blank systemPrompt in build(). The system prompt defines the sub-agent's behavior when it runs; without it the sub-agent would execute with no instructions. The builder throws IllegalArgumentException if systemPrompt is null or whitespace-only.","triggerScenarios":"Calling SubAgentSpec.builder()...build() without calling systemPrompt(String), or passing null/\"\"/blank text to systemPrompt().","commonSituations":"Loading prompts from external files/config at startup where the file is missing or empty; refactoring that moved the prompt to a placeholder not yet filled; quick prototypes that set only name and description.","solutions":["Provide the prompt via systemPrompt(...) before build().","If the prompt is loaded from a resource/config, assert it loaded non-empty before building and fail with the resource path in the message.","Use a shared constant or template for standard prompts to avoid blank placeholders."],"exampleFix":"// before\nSubAgentSpec spec = SubAgentSpec.builder()\n    .name(\"billing-agent\")\n    .description(\"Handles billing questions\")\n    .systemPrompt(null)\n    .build();\n// after\nSubAgentSpec spec = SubAgentSpec.builder()\n    .name(\"billing-agent\")\n    .description(\"Handles billing questions\")\n    .systemPrompt(\"You are a billing support agent. Answer questions about invoices and payments.\")\n    .build();","handlingStrategy":"validation","validationCode":"String prompt = loadPrompt(\"billing-agent\");\nif (prompt == null || prompt.trim().isEmpty()) {\n    throw new IllegalStateException(\"Prompt for billing-agent is empty or missing\");\n}","typeGuard":"static boolean hasText(String s) { return s != null && !s.trim().isEmpty(); }","tryCatchPattern":"try {\n    spec = SubAgentSpec.builder().systemPrompt(prompt).build();\n} catch (IllegalArgumentException e) {\n    log.error(\"System prompt missing: {}\", e.getMessage());\n}","preventionTips":["Verify prompt resources exist and are non-empty at startup.","Keep prompts as constants or validated templates instead of inline nulls.","Fail fast when a prompt file load returns blank content."],"tags":["java","builder-validation","subagent","system-prompt"],"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"}