{"record":{"id":"0eabcdfda04dbd27","repo":"alibaba/spring-ai-alibaba","slug":"agentscope-routing-flow-requires-agentscopemodel-i","errorCode":null,"errorMessage":"AgentScope routing flow requires agentScopeModel in config custom properties","messagePattern":"AgentScope routing flow requires agentScopeModel in config custom properties","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-boot-starters/spring-ai-alibaba-starter-agentscope/src/main/java/com/alibaba/cloud/ai/agent/agentscope/flow/AgentScopeRoutingGraphBuildingStrategy.java","lineNumber":135,"sourceCode":"\t\treturn () -> {\n\t\t\tMap<String, com.alibaba.cloud.ai.graph.KeyStrategy> strategies = new HashMap<>(parent.apply());\n\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\tvalidateAgentScopeRoutingConfig(config);\n\t}\n\n\tprivate void validateAgentScopeRoutingConfig(FlowGraphBuilder.FlowGraphConfig config) {\n\t\tif (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {\n\t\t\tthrow new IllegalArgumentException(\"AgentScope routing flow requires at least one sub-agent\");\n\t\t}\n\t\tif (config.getCustomProperty(\"agentScopeModel\") == null) {\n\t\t\tthrow new IllegalArgumentException(\"AgentScope routing flow requires agentScopeModel in config custom properties\");\n\t\t}\n\t\tif (!(config.getRootAgent() instanceof AgentScopeRoutingAgent)) {\n\t\t\tthrow new IllegalArgumentException(\"AgentScope routing flow requires root agent to be AgentScopeRoutingAgent\");\n\t\t}\n\t}\n}\n","sourceCodeStart":117,"sourceCodeEnd":142,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-boot-starters/spring-ai-alibaba-starter-agentscope/src/main/java/com/alibaba/cloud/ai/agent/agentscope/flow/AgentScopeRoutingGraphBuildingStrategy.java#L117-L142","documentation":"AgentScopeRoutingGraphBuildingStrategy.validateAgentScopeRoutingConfig() requires the FlowGraphConfig custom property \"agentScopeModel\" to be set; the routing merge node needs a Model to route sub-agent outputs. A null value throws IllegalArgumentException during validateConfig/buildCoreGraph.","triggerScenarios":"Building an AgentScope routing flow without putting a Model under the \"agentScopeModel\" key in the FlowGraphConfig custom properties map.","commonSituations":"Missed the customProperty(...) call when configuring the FlowGraphBuilder; custom property key typo'd; model resolved lazily and was null when config was built; followed docs for a different agent type that doesn't need this property.","solutions":["Set config.customProperty(\"agentScopeModel\", model) with a valid Model instance when building the flow.","Verify the exact property key \"agentScopeModel\" (no typos/case differences).","Ensure the model itself is non-null and correctly constructed (check provider API keys).","Alternatively configure the model directly on the AgentScopeRoutingAgent builder so it is available to the strategy."],"exampleFix":"// before\nFlowGraphBuilder builder = new FlowGraphBuilder();\nbuilder.routing(config); // missing agentScopeModel -> IllegalArgumentException\n// after\nconfig.customProperty(\"agentScopeModel\", chatModel);\nbuilder.routing(config);","handlingStrategy":"validation","validationCode":"// Java: ensure custom property is present before building\nObject model = config.getCustomProperty(\"agentScopeModel\");\nif (model == null) {\n    throw new IllegalStateException(\"Set config.customProperty(\\\"agentScopeModel\\\", model) before building the routing flow\");\n}","typeGuard":null,"tryCatchPattern":"// Java\ntry {\n    flow = builder.build();\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"agentScopeModel\")) {\n        LOGGER.warn(\"Routing flow config missing agentScopeModel; add the custom property and rebuild\");\n    }\n    throw e;\n}","preventionTips":["Centralize routing-flow config construction in one helper that always sets agentScopeModel.","Define the property key as a shared constant to avoid typos.","Validate custom properties in a unit test before wiring the flow."],"tags":["agentscope","routing","missing-config","custom-property","illegal-argument"],"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"}