{"record":{"id":"670d2b5db4f2ee28","repo":"alibaba/spring-ai-alibaba","slug":"parallel-flow-requires-at-least-one-sub-agent","errorCode":null,"errorMessage":"Parallel flow requires at least one sub-agent","messagePattern":"Parallel flow requires at least one sub-agent","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/ParallelGraphBuildingStrategy.java","lineNumber":153,"sourceCode":"\t\t\treturn strategies;\n\t\t}\n\t\tfor (Hook hook : hooks) {\n\t\t\tMap<String, KeyStrategy> hookStrategies = hook.getKeyStrategys();\n\t\t\tif (hookStrategies != null && !hookStrategies.isEmpty()) {\n\t\t\t\tstrategies.putAll(hookStrategies);\n\t\t\t}\n\t\t}\n\t\treturn strategies;\n\t}\n\n\t/**\n\t * Validates parallel-specific configuration requirements.\n\t * @param config the configuration to validate\n\t * @throws IllegalArgumentException if validation fails\n\t */\n\tprivate void validateParallelConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tif (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"Parallel flow requires at least one sub-agent\");\n\t\t}\n\n\t\tif (config.getSubAgents().size() < 2) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"Parallel flow requires at least 2 sub-agents for meaningful parallel execution\");\n\t\t}\n\n\t\t// Ensure root agent is a FlowAgent for input key access\n\t\tif (!(config.getRootAgent() instanceof FlowAgent)) {\n\t\t\tthrow new IllegalArgumentException(\"Parallel flow requires root agent to be a FlowAgent\");\n\t\t}\n\n\t\t// Validate maxConcurrency if provided\n\t\tInteger maxConcurrency = (Integer) config.getCustomProperty(\"maxConcurrency\");\n\t\tif (maxConcurrency != null && maxConcurrency < 1) {\n\t\t\tthrow new IllegalArgumentException(\"maxConcurrency must be at least 1, but got: \" + maxConcurrency);\n\t\t}\n\t}","sourceCodeStart":135,"sourceCodeEnd":171,"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/strategy/ParallelGraphBuildingStrategy.java#L135-L171","documentation":"Thrown by ParallelGraphBuildingStrategy.validateParallelConfig when the config's sub-agents list is null or empty. A parallel flow fans out work across multiple sub-agents, so at least one is mandatory for the graph to be built. This check runs before the stricter two-agent check (error 579).","triggerScenarios":"Building a ParallelAgent/parallel flow without calling subAgent(...) at all; the sub-agents list passed as null; agent-collection field never populated before build.","commonSituations":"Dynamically assembling sub-agents from config where the source list was empty; forgot to add agents; a filtering step removed all candidates before build.","solutions":["Add at least one (ideally two or more) sub-agent before building: parallelAgent.subAgent(a).subAgent(b).","Validate the source collection is non-empty before constructing the flow.","Use a different flow type if a single agent is all you have."],"exampleFix":"// before\nnew ParallelAgent(\"fanout\"); // no sub-agents\n// after\nnew ParallelAgent(\"fanout\")\n    .subAgent(agentA)\n    .subAgent(agentB);","handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["java","parallel-agent","config-validation","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-14T05:17:10.506Z"}