alibaba/spring-ai-alibaba · error · IllegalArgumentException

ElementClassType is required

Error message

ElementClassType is required

What it means

ListOperatorNode's Builder.build() throws IllegalArgumentException when the node mode is Mode.JSON_STR but no element ClassType was provided via type(...). In JSON_STR mode the node must know the target element class to deserialize each JSON element, so a missing type makes the node unusable. This is a builder-time validation guard, thrown immediately at graph construction.

Solutions

1. Call .type(YourElementClass.class) on the builder before build()
2. If you don't need JSON deserialization to a typed element, switch the builder to a non-JSON_STR mode (e.g. Mode.LIST)
3. Inspect the builder chain to confirm mode was intentionally set to JSON_STR

Example fix

// before
new ListOperatorNode.Builder<String>(Mode.JSON_STR)
    .inputKey("items").outputKey("result")
    .build();
// after
new ListOperatorNode.Builder<String>(Mode.JSON_STR)
    .inputKey("items").outputKey("result")
    .type(String.class)
    .build();

if (mode == ListOperatorNode.Mode.JSON_STR && elementType == null) {
    throw new IllegalStateException("type(...) must be set for Mode.JSON_STR");
}

boolean isJsonModeWith_type(ListOperatorNode.Builder<?> b) { return builderMode == ListOperatorNode.Mode.JSON_STR && elementType != null; }

try { node = builder.build(); } catch (IllegalArgumentException e) { /* add .type(...) and rebuild */ }

When it happens

Trigger: Calling ListOperatorNode.Builder with mode(Mode.JSON_STR) (or leaving the default mode) and never calling type(SomeClass.class) before build().

Common situations: Copy-pasting a builder example that only sets filters/comparator/limit; switching to JSON_STR mode later and forgetting that type is mandatory in that mode; misreading type(...) as optional for all modes.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Agent name must not be empty
• At least one limit must be specified (threadLimit or…
• At least one limit must be specified (threadLimit or…
• ChatModel must be provided for LLM routing agent
• Either chatClient or model must be provided

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

Appendix: source

Thrown at spring-boot-starters/spring-ai-alibaba-starter-builtin-nodes/src/main/java/com/alibaba/cloud/ai/graph/node/ListOperatorNode.java:196

		public Builder<T> limitNumber(Long limitNumber) {
			this.limitNumber = limitNumber;
			return this;
		}

		public Builder<T> limitNumber(Integer limitNumber) {
			this.limitNumber = Long.valueOf(limitNumber);
			return this;
		}

		public Builder<T> elementClassType(Class<T> type) {
			this.type = type;
			return this;
		}

		public ListOperatorNode<T> build() {
			if (type == null && mode == Mode.JSON_STR) {
				throw new IllegalArgumentException("ElementClassType is required");
			}
			// Merge List<Predicate> and List<Comparator> into a single Predicate and a
			// single Comparator, respectively.
			return new ListOperatorNode<T>(mode, inputKey, outputKey,
					filters.stream().reduce(Predicate::and).orElse(t -> true),
					comparators.stream().reduce(Comparator::thenComparing).orElse((a, b) -> 0), limitNumber, type);
		}

	}

	public static <T> Builder<T> builder() {
		return new Builder<T>();
	}

}

View on GitHub (pinned to f82da0b50f)