{"record":{"id":"8ec3c33fd1aef6d3","repo":"alibaba/spring-ai-alibaba","slug":"routing-flow-requires-at-least-one-sub-agent","errorCode":null,"errorMessage":"Routing flow requires at least one sub-agent","messagePattern":"Routing 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/RoutingGraphBuildingStrategy.java","lineNumber":151,"sourceCode":"\t\t\tstrategies.put(RoutingMergeNode.DEFAULT_MERGED_OUTPUT_KEY, new ReplaceStrategy());\n\t\t\treturn strategies;\n\t\t};\n\t}\n\n\t@Override\n\tpublic void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tsuper.validateConfig(config);\n\t\tvalidateRoutingConfig(config);\n\t}\n\n\t/**\n\t * Validates routing-specific configuration requirements.\n\t * @param config the configuration to validate\n\t * @throws IllegalArgumentException if validation fails\n\t */\n\tprivate void validateRoutingConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tif (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"Routing flow requires at least one sub-agent\");\n\t\t}\n\n\t\tif (config.getChatModel() == null) {\n\t\t\tthrow new IllegalArgumentException(\"Routing flow requires a ChatModel for decision making\");\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(\"Routing flow requires root agent to be a FlowAgent\");\n\t\t}\n\t}\n\n}\n","sourceCodeStart":133,"sourceCodeEnd":165,"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/RoutingGraphBuildingStrategy.java#L133-L165","documentation":"validateRoutingConfig in RoutingGraphBuildingStrategy throws IllegalArgumentException when a routing (Router) flow is built with no sub-agents — there would be nothing to route to, so config is rejected before graph construction.","triggerScenarios":"Building a RoutingAgent/flow graph with subAgents left unset, set to an empty list, or cleared before buildCoreGraph/validateConfig runs.","commonSituations":"Forgetting to call .subAgents(...) on the builder; programmatically constructing config where the list population was skipped; conditional code that adds no branches.","solutions":["Register at least one sub-agent via the builder's subAgents(...) method","Check that branch-adding code actually executed (no early return before adding)","Assert subAgents is non-empty before calling build()"],"exampleFix":"// before\nRoutingAgent.builder().chatModel(model).build();\n// after\nRoutingAgent.builder().chatModel(model).subAgents(agentA, agentB).build();","handlingStrategy":"validation","validationCode":"if (subAgents == null || subAgents.isEmpty()) {\n    throw new IllegalArgumentException(\"Routing flow requires at least one sub-agent\");\n}","typeGuard":"static boolean hasBranches(List<? extends Agent> l) { return l != null && !l.isEmpty(); }","tryCatchPattern":null,"preventionTips":["Always call .subAgents(...) when building a routing agent","Check builder code for early returns that skip branch registration","Assert non-empty sub-agent list in tests before build()"],"tags":["java","agent-framework","routing","validation"],"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"}