{"record":{"id":"ca6d87ae78cb6dc2","repo":"alibaba/spring-ai-alibaba","slug":"parallel-flow-requires-at-least-2-sub-agents-for-m","errorCode":null,"errorMessage":"Parallel flow requires at least 2 sub-agents for meaningful parallel execution","messagePattern":"Parallel flow requires at least 2 sub-agents for meaningful parallel execution","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":157,"sourceCode":"\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}\n\n}\n","sourceCodeStart":139,"sourceCodeEnd":174,"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#L139-L174","documentation":"Thrown by ParallelGraphBuildingStrategy.validateParallelConfig when the config has exactly one sub-agent. While one sub-agent technically passes the non-empty check, the strategy rejects it because parallel execution of a single agent is meaningless overhead; at least two sub-agents are required for meaningful parallel fan-out.","triggerScenarios":"Building a parallel flow with exactly one subAgent(...) call; dynamic agent list ended up with one element after filtering; intended sequential behavior but chose parallel strategy.","commonSituations":"Config-driven assembly where only one worker was defined; code migrated from sequential to parallel without adding agents; tests reusing a single-agent fixture.","solutions":["Add a second (or more) sub-agent so the parallel fan-out is meaningful.","If only one agent is needed, use a sequential/single-agent flow instead of parallel.","Guard the build: if subAgents.size() < 2, fall back to a different flow type."],"exampleFix":"// before\nnew ParallelAgent(\"fanout\").subAgent(agentA); // only 1\n// after\nnew ParallelAgent(\"fanout\")\n    .subAgent(agentA)\n    .subAgent(agentB);","handlingStrategy":"validation","validationCode":"if (config.getSubAgents() != null && config.getSubAgents().size() < 2) { throw new IllegalStateException(\"Parallel flow needs >= 2 sub-agents; use sequential otherwise\"); }","typeGuard":null,"tryCatchPattern":"try { parallelStrategy.validateConfig(config); } catch (IllegalArgumentException e) { log.warn(\"Falling back to sequential flow: {}\", e.getMessage()); }","preventionTips":["Reserve the parallel strategy for genuinely concurrent, multi-agent workloads.","Check sub-agent count at configuration load time.","Add a fallback path to a sequential flow for single-agent cases."],"tags":["java","parallel-agent","config-validation","sub-agents"],"backgroundTag":"value-out-of-range","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"}