{"record":{"id":"f36df3cbb3561a98","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-scan-file-system-for-items","errorCode":null,"errorMessage":"Failed to scan file system for items","messagePattern":"Failed to scan file system for items","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/FileSystemStore.java","lineNumber":312,"sourceCode":"\t\tList<StoreItem> items = new ArrayList<>();\n\t\tif (!Files.exists(rootPath)) {\n\t\t\treturn items;\n\t\t}\n\n\t\ttry {\n\t\t\tFiles.walk(rootPath).filter(path -> path.toString().endsWith(\".json\")).forEach(path -> {\n\t\t\t\ttry {\n\t\t\t\t\tString itemJson = Files.readString(path);\n\t\t\t\t\tStoreItem item = objectMapper.readValue(itemJson, StoreItem.class);\n\t\t\t\t\titems.add(item);\n\t\t\t\t}\n\t\t\t\tcatch (Exception e) {\n\t\t\t\t\t// Skip invalid files\n\t\t\t\t}\n\t\t\t});\n\t\t}\n\t\tcatch (IOException e) {\n\t\t\tthrow new RuntimeException(\"Failed to scan file system for items\", e);\n\t\t}\n\n\t\treturn items;\n\t}\n\n\t/**\n\t * Scan directories for namespaces.\n\t * @param path current path\n\t * @param currentNamespace current namespace path\n\t * @param namespaceSet set to collect namespaces\n\t * @param request namespace request\n\t */\n\tprivate void scanDirectoriesForNamespaces(Path path, List<String> currentNamespace, Set<String> namespaceSet,\n\t\t\tNamespaceListRequest request) {\n\t\ttry {\n\t\t\tif (!Files.exists(path) || !Files.isDirectory(path)) {\n\t\t\t\treturn;\n\t\t\t}","sourceCodeStart":294,"sourceCodeEnd":330,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/FileSystemStore.java#L294-L330","documentation":"FileSystemStore.getAllItems walks the store root with Files.walk and wraps IOException in RuntimeException('Failed to scan file system for items'). Called by allItems() and size(), it fails when the root tree cannot be traversed.","triggerScenarios":"store.getAllItems(), allItems(), or size() is invoked while the root directory is missing/unreadable, permissions deny traversal, or a symbolic link loop / too-many-open-files occurs during Files.walk.","commonSituations":"Root deleted at runtime by an external process; permission changes after deployment; huge stores exhausting file descriptors; NFS stale handles.","solutions":["Check the wrapped IOException cause for the failing path","Ensure the store root exists and is readable/traversable by the process user","Reinitialize the store (or recreate the root directory) if it was deleted externally","Increase file descriptor limits for very large stores"],"exampleFix":"// before\nint count = store.size();\n// after\ntry {\n    int count = store.size();\n} catch (RuntimeException e) {\n    log.warn(\"store scan failed, recreating root\", e.getCause());\n    store.clear(); // reinitializes root\n}","handlingStrategy":"try-catch","validationCode":"Path root = Path.of(storeRoot);\nif (!Files.isDirectory(root) || !Files.isReadable(root)) {\n    throw new IllegalStateException(\"store root missing or unreadable\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    List<StoreItem> items = store.getAllItems();\n} catch (RuntimeException e) {\n    logger.error(\"scan failed: {}\", e.getCause());\n    items = List.of(); // degrade gracefully\n}","preventionTips":["Monitor store root existence in health checks","Raise ulimit -n for large stores","Avoid deleting the root externally while the app runs"],"tags":["filesystem","io","scan"],"backgroundTag":"directory-not-found","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"}