{"record":{"id":"d1457a2e896df4b8","repo":"alibaba/spring-ai-alibaba","slug":"root-agent-must-be-provided","errorCode":null,"errorMessage":"Root agent must be provided","messagePattern":"Root agent must be provided","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/FlowGraphBuildingStrategy.java","lineNumber":74,"sourceCode":"\t * @return the strategy type identifier\n\t */\n\tString getStrategyType();\n\n\t/**\n\t * Validates that the configuration contains all required parameters for this\n\t * strategy.\n\t * @param config the configuration to validate\n\t * @throws IllegalArgumentException if validation fails\n\t */\n\tdefault void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tif (config == null) {\n\t\t\tthrow new IllegalArgumentException(\"Configuration cannot be null\");\n\t\t}\n\t\tif (config.getName() == null || config.getName().trim().isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"Graph name must be provided\");\n\t\t}\n\t\tif (config.getRootAgent() == null) {\n\t\t\tthrow new IllegalArgumentException(\"Root agent must be provided\");\n\t\t}\n\t\tif (config.getKeyStrategyFactory() == null) {\n\t\t\t// Generate a new KeyStrategyFactory based on agent keys\n\t\t\tKeyStrategyFactory generatedFactory = generateKeyStrategyFactory(config);\n\t\t\tconfig.keyStrategyFactory(generatedFactory);\n\t\t}\n\t}\n\n\t/**\n\t * Generates a KeyStrategyFactory based on the root agent and sub-agents.\n\t * @param config the configuration containing agents\n\t * @return the generated KeyStrategyFactory\n\t */\n\tdefault KeyStrategyFactory generateKeyStrategyFactory(FlowGraphBuilder.FlowGraphConfig config) {\n\t\treturn () -> {\n\t\t\tMap<String, KeyStrategy> keyStrategyMap = new HashMap<>();\n\t\t\tKeyStrategy defaultStrategy = new ReplaceStrategy();\n","sourceCodeStart":56,"sourceCodeEnd":92,"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/FlowGraphBuildingStrategy.java#L56-L92","documentation":"A flow graph must have a root agent to serve as entry point; validateConfig throws IllegalArgumentException when config.getRootAgent() is null. The root agent also determines generated key strategies, so building cannot continue.","triggerScenarios":"Builder used without rootAgent(...), or root agent variable still null because agent construction failed earlier / was conditional.","commonSituations":"Instantiating the builder before the agent is created; a factory method returning null on failed agent initialization; wiring order issues in Spring configuration.","solutions":["Call .rootAgent(agent) with a fully constructed agent before build()","Verify agent construction did not return null (check factory/bean creation logs)","Fix Spring wiring order so the agent bean exists when the graph is built"],"exampleFix":"// before\nFlowGraphBuilder.builder().name(\"flow\").build(); // no root\n// after\nFlowGraphBuilder.builder().name(\"flow\").rootAgent(myAgent).build();","handlingStrategy":"validation","validationCode":"Objects.requireNonNull(agent, \"Root agent must be constructed before building the flow graph\");","typeGuard":"static boolean hasRoot(FlowGraphBuilder.FlowGraphConfig c) { return c.getRootAgent() != null; }","tryCatchPattern":"try { return builder.build(); } catch (IllegalArgumentException e) { throw new FlowBuildException(\"Graph build failed: \" + e.getMessage(), e); }","preventionTips":["Construct agents before the builder; never pass possibly-null agent variables","Check factory/bean creation logs for null agent results","Order Spring bean dependencies so agents exist before graph beans"],"tags":["configuration","graph-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"}