{"record":{"id":"268a0db57809265d","repo":"alibaba/spring-ai-alibaba","slug":"loop-flow-requires-a-valid-loopstrategy-got-null","errorCode":null,"errorMessage":"Loop flow requires a valid LoopStrategy. Got: null","messagePattern":"Loop flow requires a valid LoopStrategy\\. Got: null","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":160,"sourceCode":"\t\t\treturn Stream.of(baseStrategies, loopStrategies)\n\t\t\t\t\t.flatMap(map -> map.entrySet().stream())\n\t\t\t\t\t.collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue, (k1, k2) -> k1));\n\t\t};\n\t}\n\n\t/**\n\t * Validates loop-specific configuration requirements.\n\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":142,"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#L142-L173","documentation":"Thrown by LoopGraphBuildingStrategy.validateConfig when the FlowGraphConfig's custom property LOOP_STRATEGY is not an instance of LoopStrategy (including when absent, i.e. null). A loop flow needs a concrete LoopStrategy to decide when to stop iterating; anything else makes the graph unbuildable. The message includes the actual class name or 'null' to pinpoint the mismatch.","triggerScenarios":"Building a LoopAgent/loop flow without setting config custom property LoopAgent.LOOP_STRATEGY; setting LOOP_STRATEGY to an object of the wrong class (e.g. a plain Integer count or a custom class not implementing LoopStrategy); property set under a different key than LoopAgent.LOOP_STRATEGY.","commonSituations":"Copy-pasted loop agent config that omitted the loop strategy; API change replaced an int max-iterations config with a LoopStrategy implementation; custom stopping logic implemented without implementing the LoopStrategy interface.","solutions":["Set a LoopStrategy implementation, e.g. config.addCustomProperty(LoopAgent.LOOP_STRATEGY, new MaxIterationsLoopStrategy(n)) or the builder API equivalent.","If you have custom logic, implement the LoopStrategy interface and register it under the LOOP_STRATEGY key.","Verify the property key matches LoopAgent.LOOP_STRATEGY exactly and is added to the FlowGraphConfig used for building."],"exampleFix":"// before\nFlowGraphConfig config = new FlowGraphConfig(); // no LOOP_STRATEGY set\nloopStrategy.validateConfig(config);\n// after\nconfig.addCustomProperty(LoopAgent.LOOP_STRATEGY, new MaxIterationsLoopStrategy(5));\nloopStrategy.validateConfig(config);","handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["java","loop-agent","config-validation","type-mismatch"],"backgroundTag":"type-mismatch","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"}