{"record":{"id":"8fa78ddd546e4d4d","repo":"alibaba/spring-ai-alibaba","slug":"conditional-flow-requires-root-agent-to-be-a-flowa","errorCode":null,"errorMessage":"Conditional flow requires root agent to be a FlowAgent","messagePattern":"Conditional flow requires root agent to be a FlowAgent","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":143,"sourceCode":"\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":125,"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#L125-L155","documentation":"validateConditionalConfig requires the config's rootAgent to be a FlowAgent instance so the strategy can access its input key for conditional routing. Any other root agent type is rejected with IllegalArgumentException during graph build.","triggerScenarios":"Passing a plain BaseAgent (or custom Agent implementation) as rootAgent while using the conditional building strategy; the cast/instanceof check in buildCoreGraph -> validateConditionalConfig fails.","commonSituations":"Mixing agent types after a refactor to the framework's agent hierarchy; wrapping a legacy agent as root; reusing a sequential-flow root agent in a conditional flow config.","solutions":["Make the root agent a FlowAgent subclass (e.g. extend FlowAgent) so it exposes the input key the conditional router needs","If a plain BaseAgent is required, use the appropriate strategy for that type instead of the conditional strategy","Check that you are not accidentally passing the wrong builder field (rootAgent vs sub-agent list)"],"exampleFix":"// before\nconfig.rootAgent(new MyPlainBaseAgent());\n// after\nconfig.rootAgent(new MyFlowAgent()); // class MyFlowAgent extends FlowAgent","handlingStrategy":"type-guard","validationCode":"if (!(rootAgent instanceof FlowAgent)) throw new IllegalArgumentException(\"Conditional flow root must be a FlowAgent, got: \" + rootAgent.getClass().getName());","typeGuard":"static boolean isFlowAgentRoot(FlowGraphBuilder.FlowGraphConfig c) { return c.getRootAgent() instanceof FlowAgent; }","tryCatchPattern":"try { return builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains(\"FlowAgent\")) { /* rebuild with FlowAgent root */ } throw e; }","preventionTips":["Always extend FlowAgent for roots of conditional flows","Centralize graph construction in one factory that enforces agent types","Review agent class hierarchy after framework upgrades"],"tags":["configuration","type-mismatch","graph-builder"],"backgroundTag":"type-mismatch","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}