{"record":{"id":"3fe84f7c27b1ea7a","repo":"alibaba/spring-ai-alibaba","slug":"loop-flow-requires-exactly-one-sub-agent-got-0","errorCode":null,"errorMessage":"Loop flow requires exactly one sub-agent. Got: 0","messagePattern":"Loop flow requires exactly one sub-agent\\. Got: 0","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/LoopGraphBuildingStrategy.java","lineNumber":168,"sourceCode":"\t * - Loop strategy must be provided and be an instance of LoopStrategy\n\t * - Exactly one sub-agent must be provided (loops execute a single agent repeatedly)\n\t */\n\t@Override\n\tpublic void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tsuper.validateConfig(config);\n\n\t\t// Validate loop strategy\n\t\tObject loopStrategyObj = config.getCustomProperty(LoopAgent.LOOP_STRATEGY);\n\t\tif (!(loopStrategyObj instanceof LoopStrategy)) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"Loop flow requires a valid LoopStrategy. Got: \" + (loopStrategyObj != null\n\t\t\t\t\t\t\t? loopStrategyObj.getClass().getName() : \"null\"));\n\t\t}\n\n\t\t// Validate sub-agent count\n\t\tList<Agent> subAgents = config.getSubAgents();\n\t\tif (subAgents == null || subAgents.size() != 1) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\t\"Loop flow requires exactly one sub-agent. Got: \" + (subAgents != null ? subAgents.size() : 0));\n\t\t}\n\t}\n}\n","sourceCodeStart":150,"sourceCodeEnd":173,"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/LoopGraphBuildingStrategy.java#L150-L173","documentation":"Thrown by LoopGraphBuildingStrategy.validateConfig when the config's sub-agents list is null or does not contain exactly one agent. A loop flow wraps a single sub-agent that is executed repeatedly until the LoopStrategy stops it; zero or multiple sub-agents are invalid. The message reports the actual count.","triggerScenarios":"Building a loop flow with no sub-agents added; calling subAgents(a, b) with two or more agents on a LoopAgent; the sub-agent list passed as null; mistakenly using loop strategy for what should be a parallel or sequential flow.","commonSituations":"Forgot to add the looped agent; refactored a sequential agent into a loop but kept multiple sub-agents; generic builder code shared across flow types passing the same multi-agent list.","solutions":["Add exactly one sub-agent to the loop flow, e.g. new LoopAgent(...).subAgent(worker).","If multiple agents should run repeatedly, wrap them in a single SequentialAgent and use that as the loop's one sub-agent.","Use ParallelGraphBuildingStrategy/SequentialAgent instead if the intent is not iteration over one agent."],"exampleFix":"// before\nnew LoopAgent(\"loop\")\n    .subAgent(a)\n    .subAgent(b); // 2 sub-agents\n// after\nnew LoopAgent(\"loop\")\n    .subAgent(new SequentialAgent(\"body\").subAgent(a).subAgent(b));","handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["java","loop-agent","config-validation","sub-agents"],"backgroundTag":"invalid-config-value","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"}