alibaba/spring-ai-alibaba · error · IllegalStateException

value {${arrayKey}} is not an array!

Error message

value {${arrayKey}} is not an array!

What it means

Generated IterationNode helper code (assistMethodCode) reads the iteration input array from state by arrayKey and accepts only java.util.List or native Object[]; anything else triggers IllegalStateException('value {arrayKey} is not an array!'). Iteration nodes require an array input to drive per-item execution.

Source

Thrown at spring-ai-alibaba-admin/spring-ai-alibaba-admin-server-start/src/main/java/com/alibaba/cloud/ai/studio/admin/builder/generator/service/generator/workflow/sections/IterationNodeSection.java:121

		public String assistMethodCode(DSLDialectType dialectType) {
			return """
					private NodeAction createIterationStartAction(
					        String arrayKey, String stateKey,
					        String itemKey, String indexKey, String flagKey,
					        int indexOffset) {
					    return state -> {
					        Object arrayObj = state.value(arrayKey).orElse(List.of());
					        List<Integer> stateList = state.value(stateKey, List.class).orElse(null);

					        List<?> arrayList;
					        if (stateList == null) {
					            // the first time in iteration
					            if (arrayObj instanceof List<?>) {
					                arrayList = new ArrayList<>((List<?>) arrayObj);
					            } else if (arrayObj.getClass().isArray()) {
					                arrayList = new ArrayList<>(Arrays.stream((Object[])arrayObj).toList());
					            } else {
					                throw new IllegalStateException("value {" + arrayKey + "} is not an array!");
					            }
					            int len = arrayList.size();
					            stateList = new ArrayList<>();
					            for (int i = 0; i < len; i++) {
					                stateList.add(i);
					            }
					        } else {
					            arrayList = (List<?>) arrayObj;
					        }

					        if(stateList.isEmpty()) {
					            return Map.of(flagKey, true);
					        }
					        int index = stateList.get(0);
					        Object item = arrayList.get(index);
					        stateList.remove(0);
					        return Map.of(arrayKey, arrayList, stateKey, stateList, itemKey, item,
					                indexKey, index + indexOffset, flagKey, false);

View on GitHub (pinned to f82da0b50f)

Solutions

1. Ensure the node feeding the iteration outputs a JSON array / List for the configured arrayKey.
2. Fix the arrayKey binding on the iteration node so it points at the actual array field in state.
3. Add an upstream code/transform node that wraps scalar output into a list, e.g. [value].

Example fix

// before (upstream code node)
return Map.of("items", firstItem);
// after
return Map.of("items", List.of(firstItem)); // or bind arrayKey to the real list field

Object arr = state.get(arrayKey);
if (!(arr instanceof List) && !(arr != null && arr.getClass().isArray()))
    throw new IllegalArgumentException("Iteration input '" + arrayKey + "' must be an array");

boolean isArrayInput(Object v) { return v instanceof List<?> || (v != null && v.getClass().isArray()); }

try { runIteration(node, state); } catch (IllegalStateException e) { if (e.getMessage().contains("is not an array")) { /* fix upstream output or arrayKey binding */ } throw e; }

When it happens

Trigger: Executing a workflow with an iteration node where state.get(arrayKey) is a String, Map, number, or null instead of a List/array on the first iteration.

Common situations: Upstream node outputs a single object rather than a list; JSON field configured as the array source is actually scalar; LLM output parsed to a string instead of an array.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• INVALID_PARAMS
• WORKFLOW_CONFIG_INVALID
• unexcepted result
• unknown component type: + componentType.getValue()
• extra tool param should be map

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