alibaba/spring-ai-alibaba · error · IllegalArgumentException

Condition keys cannot be null or empty

Error message

Condition keys cannot be null or empty

What it means

Every key in the conditionalAgents map is used as a routing condition string; validateConditionalConfig rejects null, empty, or whitespace-only keys because the router could never match them, silently breaking dispatch. Thrown as IllegalArgumentException.

Solutions

1. Sanitize condition keys before building: strip whitespace and reject/skip blank entries
2. Validate external config (YAML/Nacos/DB) at load time so blank branch names never reach the builder
3. Add a unit test asserting every conditionalAgents key is non-blank

Example fix

// before
Map<String, Agent> agents = new HashMap<>();
agents.put(blankFromConfig, agentA);
// after
String key = rawKey == null ? null : rawKey.trim();
if (key != null && !key.isEmpty()) { agents.put(key, agentA); }

config.getConditionalAgents().keySet().forEach(k -> { if (k == null || k.trim().isEmpty()) throw new IllegalArgumentException("Blank condition key in conditionalAgents"); });

static boolean allKeysNonBlank(Map<String, Agent> m) { return m == null || m.keySet().stream().allMatch(k -> k != null && !k.trim().isEmpty()); }

try { return builder.build(); } catch (IllegalArgumentException e) { log.error("Conditional config invalid: {}", e.getMessage()); throw e; }

When it happens

Trigger: Building a conditional graph with Map.of(...) cannot hold null keys, so this typically fires with HashMap usage where a key is null, or with keys like "" or " " produced by dynamic configuration (Nacos config, DB rows, YAML lists).

Common situations: Loading branch conditions from external config where an entry has no name; trimming failed; programmatically generated keys where a variable was empty.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• At least one fallback model must be specified
• Conditional flow requires at least one conditional agent…
• database cannot be null or blank
• dbType cannot be null or blank
• Graph name must be provided

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

Appendix: source

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

	/**
	 * 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)