{"record":{"id":"603e73dda7674884","repo":"alibaba/spring-ai-alibaba","slug":"loopagent-must-have-a-loopstrategy","errorCode":null,"errorMessage":"LoopAgent must have a loopStrategy.","messagePattern":"LoopAgent must have a loopStrategy\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/LoopAgent.java","lineNumber":107,"sourceCode":"            this.subAgents = List.of(subAgent);\n            return self();\n        }\n\n        @Override\n        public LoopAgentBuilder subAgents(List<Agent> subAgents) {\n            throw new UnsupportedOperationException(\"LoopAgent must have only one subAgent, please use subAgent() method.\");\n        }\n\n        public LoopAgentBuilder loopStrategy(LoopStrategy loopStrategy) {\n            this.loopStrategy = loopStrategy;\n            return self();\n        }\n\n        @Override\n        protected void validate() {\n            super.validate();\n            if (this.loopStrategy == null) {\n                throw new IllegalArgumentException(\"LoopAgent must have a loopStrategy.\");\n            }\n        }\n\n        @Override\n        public LoopAgent doBuild() {\n            validate();\n            return new LoopAgent(this);\n        }\n    }\n}\n","sourceCodeStart":89,"sourceCodeEnd":118,"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/LoopAgent.java#L89-L118","documentation":"LoopAgent needs a LoopStrategy to decide when to stop iterating; its builder's validate() (run from doBuild()) throws IllegalArgumentException if loopStrategy was never set. Without a strategy the loop would have no termination condition.","triggerScenarios":"Calling LoopAgent.builder()...build() without loopStrategy(...), or passing null to loopStrategy().","commonSituations":"Examples written before loopStrategy became mandatory after a version upgrade; building the loop conditionally where the strategy assignment branch is skipped; forgetting the strategy because subAgent() alone compiles fine.","solutions":["Add loopStrategy(...) with an appropriate strategy (e.g., max iterations or a condition-based strategy) before build().","Check the library version's docs/examples — the required strategy API may have changed on upgrade.","If iteration count is the only need, use a simple max-iterations strategy; otherwise supply a condition-backed LoopStrategy."],"exampleFix":"// before\nLoopAgent agent = LoopAgent.builder()\n    .subAgent(workerAgent)\n    .build(); // throws: LoopAgent must have a loopStrategy.\n// after\nLoopAgent agent = LoopAgent.builder()\n    .subAgent(workerAgent)\n    .loopStrategy(LoopStrategy.maxIterations(5))\n    .build();","handlingStrategy":"validation","validationCode":"Objects.requireNonNull(loopStrategy, \"LoopAgent requires a LoopStrategy before build()\");\nLoopAgent agent = LoopAgent.builder().subAgent(a).loopStrategy(loopStrategy).build();","typeGuard":"static boolean loopAgentReady(LoopStrategy s) { return s != null; }","tryCatchPattern":"try {\n    agent = loopBuilder.build();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"loopStrategy\")) {\n        log.error(\"LoopAgent built without loopStrategy; add loopStrategy(...)\");\n    }\n}","preventionTips":["Treat subAgent() + loopStrategy() as an inseparable pair when configuring LoopAgent.","Check upgrade notes: older examples may predate the mandatory strategy.","Default to a max-iterations strategy to guarantee termination."],"tags":["java","loop-agent","builder-validation"],"backgroundTag":"missing-required-argument","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"}