{"record":{"id":"a1f7734b1533c507","repo":"alibaba/spring-ai-alibaba","slug":"variable-filelist-is-not-an-arrayfilesegment","errorCode":null,"errorMessage":"Variable fileList is not an ArrayFileSegment","messagePattern":"Variable fileList is not an ArrayFileSegment","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-boot-starters/spring-ai-alibaba-starter-builtin-nodes/src/main/java/com/alibaba/cloud/ai/graph/node/DocumentExtractorNode.java","lineNumber":140,"sourceCode":"\t\tif (this.inputIsArray) {\n\t\t\tif (fileObj instanceof List<?>) {\n\t\t\t\tfileList = (List<String>) fileObj;\n\t\t\t}\n\t\t\telse if (fileObj instanceof String[]) {\n\t\t\t\tfileList = Arrays.asList((String[]) fileObj);\n\t\t\t}\n\t\t\telse {\n\t\t\t\t// Try to parse as Json string, if failed the input is invalid\n\t\t\t\ttry {\n\t\t\t\t\tfileList = JsonParser.fromJson(fileObj.toString(), new TypeReference<List<String>>() {\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tcatch (Exception ignore) {\n\t\t\t\t\tfileList = null;\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (fileList == null || fileList.isEmpty()) {\n\t\t\t\tthrow new RuntimeException(\"Variable fileList is not an ArrayFileSegment\");\n\t\t\t}\n\t\t}\n\t\telse {\n\t\t\t// Single file, add directly to the list\n\t\t\tfileList = List.of(fileObj.toString());\n\t\t}\n\t\tList<String> documentContents = this.getDocument(fileList);\n\n\t\tString key = Optional.ofNullable(this.outputKey).orElse(\"text\");\n\t\tif (!this.inputIsArray) {\n\t\t\treturn Map.of(key, documentContents.get(0));\n\t\t}\n\t\telse {\n\t\t\treturn Map.of(key, documentContents);\n\t\t}\n\t}\n\n\tprivate String extractTextByFileExtension(InputStream fileContent, String fileExtension) {","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-boot-starters/spring-ai-alibaba-starter-builtin-nodes/src/main/java/com/alibaba/cloud/ai/graph/node/DocumentExtractorNode.java#L122-L158","documentation":"DocumentExtractorNode.apply throws this RuntimeException in the inputIsArray branch when, after attempting to coerce the state value, fileList is null or empty — i.e. the value at paramsKey was not a usable ArrayFileSegment (list of file segments).","triggerScenarios":"inputIsArray=true but the state value under paramsKey is a single string, a Map, or an object that fails conversion to a list of files, leaving fileList null after the catch block sets it to null.","commonSituations":"Upstream node writes a single file string while the extractor expects an array of ArrayFileSegment; state key never populated; shape change after upgrading the file-segment representation; JSON-deserialized state loses the segment type.","solutions":["Make the upstream node emit an ArrayFileSegment (list of file segments) under paramsKey","Set inputIsArray=false if the input is actually a single file","Log/inspect the actual type of state.value(paramsKey) and align it with the extractor's expectation"],"exampleFix":"// before\nstate.put(\"files\", singleFileString); // node has inputIsArray=true\n// after\nstate.put(\"files\", List.of(fileSegment1, fileSegment2));","handlingStrategy":"type-guard","validationCode":"Object v = state.value(paramsKey).orElse(null);\nif (inputIsArray && !(v instanceof List<?> list && !list.isEmpty())) {\n    throw new IllegalStateException(\"paramsKey must hold a non-empty ArrayFileSegment list\");\n}","typeGuard":"static boolean isArrayFileSegment(Object v) {\n    return v instanceof List<?> l && !l.isEmpty() && l.get(0) instanceof FileSegment;\n}","tryCatchPattern":"try {\n    out = extractorNode.apply(state);\n} catch (RuntimeException e) {\n    logger.error(\"fileList shape wrong: {}\", e.getMessage());\n    out = Map.of(outputKey, List.of());\n}","preventionTips":["Match inputIsArray to the actual shape of the state value (array vs single file)","Have the upstream node emit ArrayFileSegment explicitly when inputIsArray=true","Add a state-shape assertion between producer and consumer nodes"],"tags":["document-extraction","type-mismatch","file-segment","inputisarray"],"backgroundTag":"type-mismatch","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}