alibaba/spring-ai-alibaba · error · IllegalArgumentException

Conditional flow requires at least one conditional agent map

Error message

Conditional flow requires at least one conditional agent mapping

What it means

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.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/strategy/ConditionalGraphBuildingStrategy.java:138

	@Override
	public String getStrategyType() {
		return FlowAgentEnum.CONDITIONAL.getType();
	}

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

	/**
	 * Validates conditional-specific configuration requirements.
	 * @param config the configuration to validate
	 * @throws IllegalArgumentException if validation fails
	 */
	private void validateConditionalConfig(FlowGraphBuilder.FlowGraphConfig config) {
		if (config.getConditionalAgents() == null || config.getConditionalAgents().isEmpty()) {
			throw new IllegalArgumentException("Conditional flow requires at least one conditional agent mapping");
		}

		// Ensure root agent is a FlowAgent for input key access
		if (!(config.getRootAgent() instanceof FlowAgent)) {
			throw new IllegalArgumentException("Conditional flow requires root agent to be a FlowAgent");
		}

		// Validate that all condition keys are non-empty
		for (String condition : config.getConditionalAgents().keySet()) {
			if (condition == null || condition.trim().isEmpty()) {
				throw new IllegalArgumentException("Condition keys cannot be null or empty");
			}
		}
	}

}

View on GitHub (pinned to f82da0b50f)

Solutions

1. Register at least one mapping, e.g. config.conditionalAgents(Map.of("sales", salesAgent, "support", supportAgent))
2. Ensure the FlowGraphBuilder strategy type actually matches the configured flow (use sequential strategy if you don't need conditional dispatch)
3. Double-check builder method chaining so conditionalAgents() is invoked before build()

Example fix

// before
FlowGraphBuilder.builder().strategy("conditional").rootAgent(router).build();
// after
FlowGraphBuilder.builder().strategy("conditional")
    .rootAgent(router)
    .conditionalAgents(Map.of("yes", agentA, "no", agentB))
    .build();

if (config.getConditionalAgents() == null || config.getConditionalAgents().isEmpty()) throw new IllegalArgumentException("Provide at least one conditionalAgents mapping before build()");

static boolean hasConditionalMappings(FlowGraphBuilder.FlowGraphConfig c) { return c.getConditionalAgents() != null && !c.getConditionalAgents().isEmpty(); }

try { return builder.build(); } catch (IllegalArgumentException e) { throw new FlowConfigException("Invalid conditional flow config: " + e.getMessage(), e); }

When it happens

Trigger: Building a conditional graph via FlowGraphBuilder with strategy=conditional but never calling the conditionalAgents(...) registration, or passing an empty map.

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

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

• Graph name must be provided
• Root agent must be provided
• WORKFLOW_CONFIG_ILLEGAL
• 模型缺少 id
• 模型缺少 name

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