alibaba/spring-ai-alibaba · error · IllegalArgumentException

AgentScope routing flow requires agentScopeModel in config c

Error message

AgentScope routing flow requires agentScopeModel in config custom properties

What it means

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.

Source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-agentscope/src/main/java/com/alibaba/cloud/ai/agent/agentscope/flow/AgentScopeRoutingGraphBuildingStrategy.java:135

		return () -> {
			Map<String, com.alibaba.cloud.ai.graph.KeyStrategy> strategies = new HashMap<>(parent.apply());
			strategies.put(RoutingMergeNode.DEFAULT_MERGED_OUTPUT_KEY, new ReplaceStrategy());
			return strategies;
		};
	}

	@Override
	public void validateConfig(FlowGraphBuilder.FlowGraphConfig config) {
		super.validateConfig(config);
		validateAgentScopeRoutingConfig(config);
	}

	private void validateAgentScopeRoutingConfig(FlowGraphBuilder.FlowGraphConfig config) {
		if (config.getSubAgents() == null || config.getSubAgents().isEmpty()) {
			throw new IllegalArgumentException("AgentScope routing flow requires at least one sub-agent");
		}
		if (config.getCustomProperty("agentScopeModel") == null) {
			throw new IllegalArgumentException("AgentScope routing flow requires agentScopeModel in config custom properties");
		}
		if (!(config.getRootAgent() instanceof AgentScopeRoutingAgent)) {
			throw new IllegalArgumentException("AgentScope routing flow requires root agent to be AgentScopeRoutingAgent");
		}
	}
}

View on GitHub (pinned to f82da0b50f)

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.

Example fix

// before
FlowGraphBuilder builder = new FlowGraphBuilder();
builder.routing(config); // missing agentScopeModel -> IllegalArgumentException
// after
config.customProperty("agentScopeModel", chatModel);
builder.routing(config);

Defensive patterns

Strategy: validation

Validate before calling

// Java: ensure custom property is present before building
Object model = config.getCustomProperty("agentScopeModel");
if (model == null) {
    throw new IllegalStateException("Set config.customProperty(\"agentScopeModel\", model) before building the routing flow");
}

Try / catch

// Java
try {
    flow = builder.build();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("agentScopeModel")) {
        LOGGER.warn("Routing flow config missing agentScopeModel; add the custom property and rebuild");
    }
    throw e;
}

Prevention

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.

When it happens

Trigger: Building an AgentScope routing flow without putting a Model under the "agentScopeModel" key in the FlowGraphConfig custom properties map.

Common situations: 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.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/0eabcdfda04dbd27. Report an issue: GitHub.