{"record":{"id":"a9c2418dad4cca48","repo":"alibaba/spring-ai-alibaba","slug":"conditional-flow-requires-at-least-one-conditional","errorCode":null,"errorMessage":"Conditional flow requires at least one conditional agent mapping","messagePattern":"Conditional flow requires at least one conditional agent mapping","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/ConditionalGraphBuildingStrategy.java","lineNumber":138,"sourceCode":"\t@Override\n\tpublic String getStrategyType() {\n\t\treturn FlowAgentEnum.CONDITIONAL.getType();\n\t}\n\n\t@Override\n\tpublic void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tsuper.validateConfig(config);\n\t\tvalidateConditionalConfig(config);\n\t}\n\n\t/**\n\t * Validates conditional-specific configuration requirements.\n\t * @param config the configuration to validate\n\t * @throws IllegalArgumentException if validation fails\n\t */\n\tprivate void validateConditionalConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tif (config.getConditionalAgents() == null || config.getConditionalAgents().isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"Conditional flow requires at least one conditional agent mapping\");\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(\"Conditional flow requires root agent to be a FlowAgent\");\n\t\t}\n\n\t\t// Validate that all condition keys are non-empty\n\t\tfor (String condition : config.getConditionalAgents().keySet()) {\n\t\t\tif (condition == null || condition.trim().isEmpty()) {\n\t\t\t\tthrow new IllegalArgumentException(\"Condition keys cannot be null or empty\");\n\t\t\t}\n\t\t}\n\t}\n\n}\n","sourceCodeStart":120,"sourceCodeEnd":155,"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/ConditionalGraphBuildingStrategy.java#L120-L155","documentation":"ConditionalGraphBuildingStrategy.validateConditionalConfig rejects a FlowGraphConfig whose conditionalAgents map is null or empty, because a conditional (routing) flow has nothing to dispatch to without at least one condition->agent mapping. Thrown as IllegalArgumentException during graph construction.","triggerScenarios":"Building a conditional graph via FlowGraphBuilder with strategy=conditional but never calling the conditionalAgents(...) registration, or passing an empty map.","commonSituations":"Builder misconfiguration: user selected the conditional strategy but configured agents via a generic addAgent call instead of conditionalAgents(); refactoring removed the mapping; fluent builder chain interrupted before registration.","solutions":["Register at least one mapping, e.g. config.conditionalAgents(Map.of(\"sales\", salesAgent, \"support\", supportAgent))","Ensure the FlowGraphBuilder strategy type actually matches the configured flow (use sequential strategy if you don't need conditional dispatch)","Double-check builder method chaining so conditionalAgents() is invoked before build()"],"exampleFix":"// before\nFlowGraphBuilder.builder().strategy(\"conditional\").rootAgent(router).build();\n// after\nFlowGraphBuilder.builder().strategy(\"conditional\")\n    .rootAgent(router)\n    .conditionalAgents(Map.of(\"yes\", agentA, \"no\", agentB))\n    .build();","handlingStrategy":"validation","validationCode":"if (config.getConditionalAgents() == null || config.getConditionalAgents().isEmpty()) throw new IllegalArgumentException(\"Provide at least one conditionalAgents mapping before build()\");","typeGuard":"static boolean hasConditionalMappings(FlowGraphBuilder.FlowGraphConfig c) { return c.getConditionalAgents() != null && !c.getConditionalAgents().isEmpty(); }","tryCatchPattern":"try { return builder.build(); } catch (IllegalArgumentException e) { throw new FlowConfigException(\"Invalid conditional flow config: \" + e.getMessage(), e); }","preventionTips":["Call conditionalAgents() immediately after selecting the conditional strategy","Write a builder-level unit test per flow type","Never mix generic addAgent with the conditional strategy"],"tags":["configuration","graph-builder","validation"],"backgroundTag":"missing-required-config-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"}