{"record":{"id":"55e1d1085b58f734","repo":"alibaba/spring-ai-alibaba","slug":"value-arraykey-is-not-an-array","errorCode":null,"errorMessage":"value {${arrayKey}} is not an array!","messagePattern":"value (.+?) is not an array!","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"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","lineNumber":121,"sourceCode":"\t\tpublic String assistMethodCode(DSLDialectType dialectType) {\n\t\t\treturn \"\"\"\n\t\t\t\t\tprivate NodeAction createIterationStartAction(\n\t\t\t\t\t        String arrayKey, String stateKey,\n\t\t\t\t\t        String itemKey, String indexKey, String flagKey,\n\t\t\t\t\t        int indexOffset) {\n\t\t\t\t\t    return state -> {\n\t\t\t\t\t        Object arrayObj = state.value(arrayKey).orElse(List.of());\n\t\t\t\t\t        List<Integer> stateList = state.value(stateKey, List.class).orElse(null);\n\n\t\t\t\t\t        List<?> arrayList;\n\t\t\t\t\t        if (stateList == null) {\n\t\t\t\t\t            // the first time in iteration\n\t\t\t\t\t            if (arrayObj instanceof List<?>) {\n\t\t\t\t\t                arrayList = new ArrayList<>((List<?>) arrayObj);\n\t\t\t\t\t            } else if (arrayObj.getClass().isArray()) {\n\t\t\t\t\t                arrayList = new ArrayList<>(Arrays.stream((Object[])arrayObj).toList());\n\t\t\t\t\t            } else {\n\t\t\t\t\t                throw new IllegalStateException(\"value {\" + arrayKey + \"} is not an array!\");\n\t\t\t\t\t            }\n\t\t\t\t\t            int len = arrayList.size();\n\t\t\t\t\t            stateList = new ArrayList<>();\n\t\t\t\t\t            for (int i = 0; i < len; i++) {\n\t\t\t\t\t                stateList.add(i);\n\t\t\t\t\t            }\n\t\t\t\t\t        } else {\n\t\t\t\t\t            arrayList = (List<?>) arrayObj;\n\t\t\t\t\t        }\n\n\t\t\t\t\t        if(stateList.isEmpty()) {\n\t\t\t\t\t            return Map.of(flagKey, true);\n\t\t\t\t\t        }\n\t\t\t\t\t        int index = stateList.get(0);\n\t\t\t\t\t        Object item = arrayList.get(index);\n\t\t\t\t\t        stateList.remove(0);\n\t\t\t\t\t        return Map.of(arrayKey, arrayList, stateKey, stateList, itemKey, item,\n\t\t\t\t\t                indexKey, index + indexOffset, flagKey, false);","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/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#L103-L139","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the node feeding the iteration outputs a JSON array / List for the configured arrayKey.","Fix the arrayKey binding on the iteration node so it points at the actual array field in state.","Add an upstream code/transform node that wraps scalar output into a list, e.g. [value]."],"exampleFix":"// before (upstream code node)\nreturn Map.of(\"items\", firstItem);\n// after\nreturn Map.of(\"items\", List.of(firstItem)); // or bind arrayKey to the real list field","handlingStrategy":"type-guard","validationCode":"Object arr = state.get(arrayKey);\nif (!(arr instanceof List) && !(arr != null && arr.getClass().isArray()))\n    throw new IllegalArgumentException(\"Iteration input '\" + arrayKey + \"' must be an array\");","typeGuard":"boolean isArrayInput(Object v) { return v instanceof List<?> || (v != null && v.getClass().isArray()); }","tryCatchPattern":"try { runIteration(node, state); } catch (IllegalStateException e) { if (e.getMessage().contains(\"is not an array\")) { /* fix upstream output or arrayKey binding */ } throw e; }","preventionTips":["Verify upstream nodes output lists before wiring them into iteration nodes","Double-check arrayKey bindings point at real array fields in state","Insert a transform node to wrap scalars into lists when needed"],"tags":["iteration-node","type-mismatch","workflow"],"backgroundTag":"type-mismatch","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}