alibaba/spring-ai-alibaba · error · IllegalArgumentException

outputKey must not be null or empty

Error message

outputKey must not be null or empty

What it means

ParallelResultAggregator.Builder.build() throws when outputKey is null or blank. The aggregator writes the merged parallel results into state under this key, so it is mandatory for the node to function.

Solutions

1. Call .outputKey("<state-key>") before .build()
2. Ensure the config/source feeding the key returns a non-blank string
3. Check the surrounding graph wiring reuses the same key when reading the aggregated result

Example fix

// before
new ParallelResultAggregator.Builder().build();
// after
new ParallelResultAggregator.Builder().outputKey("parallel-results").build();

if (outputKey == null || outputKey.isBlank()) throw new IllegalArgumentException("outputKey required for ParallelResultAggregator");

boolean validKey(String k) { return k != null && !k.isBlank(); }

try { node = aggregatorBuilder.build(); } catch (IllegalArgumentException e) { if (e.getMessage().contains("outputKey must not be null")) { /* set key and rebuild */ } else throw e; }

When it happens

Trigger: new ParallelResultAggregator.Builder().build() without .outputKey(...), or outputKey("") / outputKey(" ").

Common situations: outputKey sourced from a nullable config property; wiring the aggregator node in a graph builder and skipping the key; renaming a state key and leaving the aggregator call stale.

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

• AgentCard or AgentCardProvider must be provided
• At least one fallback model must be specified
• At least one sub-agent must be provided for flow
• Description must be provided
• initialDelay must be greater than or equal to 0.

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

Appendix: source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/flow/node/ParallelResultAggregator.java:81

		return updatedState;
	}

	public static Builder builder() {
		return new Builder();
	}

	public static class Builder {

		private String outputKey;

		public Builder outputKey(String outputKey) {
			this.outputKey = outputKey;
			return this;
		}

		public ParallelResultAggregator build() {
			if (outputKey == null || outputKey.trim().isEmpty()) {
				throw new IllegalArgumentException("outputKey must not be null or empty");
			}
			return new ParallelResultAggregator(outputKey);
		}

	}

}

View on GitHub (pinned to f82da0b50f)