{"record":{"id":"a2f148febe3a0ed6","repo":"alibaba/spring-ai-alibaba","slug":"parallelagent-requires-at-least-2-sub-agents-for-p","errorCode":null,"errorMessage":"ParallelAgent requires at least 2 sub-agents for parallel execution, but got: 0","messagePattern":"ParallelAgent requires at least 2 sub-agents for parallel execution, but got: 0","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/ParallelAgent.java","lineNumber":244,"sourceCode":"\t\tprotected ParallelAgentBuilder self() {\n\t\t\treturn this;\n\t\t}\n\n\t\t/**\n\t\t * Validates the builder state before creating the agent.\n\t\t * @throws IllegalArgumentException if validation fails\n\t\t */\n\t\t@Override\n\t\tprotected void validate() {\n\t\t\t// Validate name first (from parent)\n\t\t\tif (name == null || name.trim().isEmpty()) {\n\t\t\t\tthrow new IllegalArgumentException(\"Name must be provided\");\n\t\t\t}\n\n\t\t\t// Validate minimum sub-agent count for ParallelAgent (skip parent subAgents\n\t\t\t// check)\n\t\t\tif (subAgents == null || subAgents.size() < 2) {\n\t\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\t\"ParallelAgent requires at least 2 sub-agents for parallel execution, but got: \"\n\t\t\t\t\t\t\t\t+ (subAgents != null ? subAgents.size() : 0));\n\t\t\t}\n\n\t\t\t// Validate maximum sub-agent count for performance reasons\n\t\t\tif (subAgents.size() > 10) {\n\t\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\t\"ParallelAgent supports maximum 10 sub-agents for performance reasons, but got: \"\n\t\t\t\t\t\t\t\t+ subAgents.size());\n\t\t\t}\n\n\t\t\t// Validate that sub-agents have unique output keys to avoid conflicts during\n\t\t\t// result merging\n\t\t\tvalidateUniqueOutputKeys();\n\n\t\t\t// Validate input key compatibility\n\t\t\tvalidateInputKeyCompatibility();\n","sourceCodeStart":226,"sourceCodeEnd":262,"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/agent/ParallelAgent.java#L226-L262","documentation":"ParallelAgent requires at least 2 sub-agents to execute in parallel; validate() throws when subAgents is null or has fewer than 2 entries. With 0 or 1 sub-agents a parallel node is meaningless, so the builder refuses to construct it.","triggerScenarios":"ParallelAgent.builder().name(\"x\").build() with no .subAgents(...) call, or with a list containing only one agent, or an empty/null list passed explicitly.","commonSituations":"Building the sub-agent list conditionally so all branches were filtered out; refactor changed a sequential agent to parallel but kept a single sub-agent; the sub-agent list is loaded from config and came back empty.","solutions":["Pass at least 2 sub-agents via .subAgents(agentA, agentB, ...)","Verify the sub-agent collection is populated before build(); if a single agent is all you need, use the agent directly or a different flow type","Add an upstream check that the filtered sub-agent list size >= 2"],"exampleFix":"// before\nParallelAgent.builder().name(\"p\").subAgents(onlyAgent).build();\n// after\nif (agents.size() >= 2) {\n    ParallelAgent.builder().name(\"p\").subAgents(agents).build();\n}","handlingStrategy":"validation","validationCode":"if (subAgents == null || subAgents.size() < 2) throw new IllegalArgumentException(\"ParallelAgent needs >= 2 sub-agents\");","typeGuard":"boolean canBuildParallel(java.util.List<Agent> a) { return a != null && a.size() >= 2; }","tryCatchPattern":"try { agent = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"requires at least 2 sub-agents\")) { /* fall back to sequential or single agent */ } else throw e; }","preventionTips":["Assert sub-agent list size before building","Avoid filtering pipelines that can silently empty the list","Choose SequentialAgent when only one child exists"],"tags":["validation","builder","sub-agents"],"backgroundTag":"invalid-argument-value","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"}