alibaba/spring-ai-alibaba · error · IllegalArgumentException

ParallelAgent validation failed: Duplicate output keys…

Error message

ParallelAgent validation failed: Duplicate output keys found among sub-agents: []. Each sub-agent must have a unique output key to avoid conflicts during result merging.

What it means

validateUniqueOutputKeys() throws when two or more sub-agents of a ParallelAgent produce results under the same output key. Duplicate keys make the merged result state ambiguous (one agent's output would overwrite another's), so building is aborted and the duplicate key list is reported.

Solutions

1. Give each sub-agent a distinct outputKey in its own configuration
2. Inspect the reported duplicateKeys list and rename the conflicting keys
3. Ensure cloned/duplicated agents parameterize their output key

Example fix

// before
agentA.builder().outputKey("result"); agentB.builder().outputKey("result");
// after
agentA.builder().outputKey("resultA"); agentB.builder().outputKey("resultB");

Set<String> keys = subAgents.stream().map(a -> a.outputKey()).collect(java.util.stream.Collectors.toSet()); if (keys.size() != subAgents.size()) throw new IllegalStateException("Duplicate output keys");

try { agent = builder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("Duplicate output keys")) { /* reassign keys and rebuild */ } else throw e; }

When it happens

Trigger: Two sub-agents configured with the same .outputKey("result") (or default key) and passed to one ParallelAgent, then .build() is called.

Common situations: Cloning an agent for scale-out without changing its output key; both sub-agents wrapping the same tool; copying a builder block and leaving outputKey unchanged.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

• outputKey must not be null or empty
• AgentCard or AgentCardProvider must be provided
• AgentScope Model must be provided for AgentScope routing…
• AgentScope routing flow requires at least one sub-agent
• appName cannot be null or empty

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

Appendix: source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/agent/ParallelAgent.java:292

		 */
		private void validateUniqueOutputKeys() {
			Set<String> outputKeys = new HashSet<>();
			Set<String> duplicateKeys = new HashSet<>();

			for (Agent subAgent : subAgents) {
				if (subAgent instanceof ReactAgent subReactAgent) {
					String outputKey = subReactAgent.getOutputKey();
					if (outputKey != null) {
						if (!outputKeys.add(outputKey)) {
							// This key was already seen, it's a duplicate
							duplicateKeys.add(outputKey);
						}
					}
				}
			}

			if (!duplicateKeys.isEmpty()) {
				throw new IllegalArgumentException(
						"ParallelAgent validation failed: Duplicate output keys found among sub-agents: "
								+ duplicateKeys
								+ ". Each sub-agent must have a unique output key to avoid conflicts during result merging.");
			}
		}

		/**
		 * Validates that sub-agents can properly receive data from the parent agent.
		 *
		 * <p>
		 * This validation checks the data flow compatibility by ensuring that:
		 * </p>
		 * <ul>
		 * <li>The parent agent has an outputKey defined</li>
		 * <li>Sub-agents can properly handle the data flow through asAsyncNodeAction</li>
		 * </ul>
		 *
		 * <p>

View on GitHub (pinned to f82da0b50f)