{"record":{"id":"ca16ff393234a5e1","repo":"alibaba/spring-ai-alibaba","slug":"at-least-one-sub-agent-must-be-provided-for-flow","errorCode":null,"errorMessage":"At least one sub-agent must be provided for flow","messagePattern":"At least one sub-agent must be provided for flow","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/builder/FlowAgentBuilder.java","lineNumber":180,"sourceCode":"\n\t/**\n\t * Returns the concrete builder instance. This method enables fluent interface support\n\t * in subclasses.\n\t * @return this builder instance\n\t */\n\tprotected abstract B self();\n\n\t/**\n\t * Validates the builder state before creating the agent. Subclasses can override this\n\t * method to add specific validation logic.\n\t * @throws IllegalArgumentException if validation fails\n\t */\n\tprotected void validate() {\n\t\tif (name == null || name.trim().isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"Name must be provided\");\n\t\t}\n\t\tif (subAgents == null || subAgents.isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"At least one sub-agent must be provided for flow\");\n\t\t}\n\t}\n\n\t/**\n\t * Builds the concrete FlowAgent instance. Subclasses must implement this method to\n\t * create the specific agent type.\n\t * @return the built FlowAgent instance\n\t * @throws GraphStateException if agent creation fails\n\t */\n\tpublic T build() {\n\t\tif (this.saver != null) {\n\t\t\tif (this.compileConfig == null) {\n\t\t\t\tthis.compileConfig = CompileConfig.builder().saverConfig(SaverConfig.builder().register(saver).build()).build();\n\t\t\t}\n\t\t\tthis.compileConfig = CompileConfig.builder(compileConfig).saverConfig(SaverConfig.builder().register(saver).build()).build();\n\t\t}\n\t\treturn doBuild();\n\t};","sourceCodeStart":162,"sourceCodeEnd":198,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/builder/FlowAgentBuilder.java#L162-L198","documentation":"FlowAgentBuilder.validate() throws when no sub-agents were provided: a flow agent by definition routes work through at least one child agent, so an empty or null subAgents list makes the flow meaningless and build() is aborted.","triggerScenarios":"Calling .build() on a flow agent builder without .subAgents(...), or passing an empty list (e.g. a conditionally populated list that ended up empty).","commonSituations":"Sub-agent list assembled from feature-flagged registrations that were all disabled; config-driven agent lists that parsed to empty; forgetting the subAgents call after refactoring.","solutions":["Provide at least one (and per ParallelAgent, two) sub-agents via .subAgents(...)","Check why the sub-agent collection is empty before building; log and fail fast upstream","If no sub-agent is truly needed, use a plain LLM agent instead of a flow agent"],"exampleFix":"// before\nif (!agents.isEmpty()) {} // agents was empty but build happened anyway\nSequentialAgent.builder().name(\"p\").subAgents(agents).build();\n// after\nif (!agents.isEmpty()) {\n    SequentialAgent.builder().name(\"p\").subAgents(agents).build();\n}","handlingStrategy":"validation","validationCode":"if (subAgents == null || subAgents.isEmpty()) throw new IllegalArgumentException(\"Flow requires >= 1 sub-agent\");","typeGuard":"boolean hasSubAgents(java.util.List<Agent> a) { return a != null && !a.isEmpty(); }","tryCatchPattern":"try { agent = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"At least one sub-agent\")) { /* register a default sub-agent */ } else throw e; }","preventionTips":["Check sub-agent registration flags at startup","Fail fast with a clear message when the list ends up empty","Don't use flow agents without children — use a plain agent instead"],"tags":["validation","builder","sub-agents"],"backgroundTag":"empty-required-field","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}