alibaba/spring-ai-alibaba · error · RuntimeException

Failed to scan file system for items

Error message

Failed to scan file system for items

What it means

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.

Solutions

1. Check the wrapped IOException cause for the failing path
2. Ensure the store root exists and is readable/traversable by the process user
3. Reinitialize the store (or recreate the root directory) if it was deleted externally
4. Increase file descriptor limits for very large stores

Example fix

// before
int count = store.size();
// after
try {
    int count = store.size();
} catch (RuntimeException e) {
    log.warn("store scan failed, recreating root", e.getCause());
    store.clear(); // reinitializes root
}

Path root = Path.of(storeRoot);
if (!Files.isDirectory(root) || !Files.isReadable(root)) {
    throw new IllegalStateException("store root missing or unreadable");
}

try {
    List<StoreItem> items = store.getAllItems();
} catch (RuntimeException e) {
    logger.error("scan failed: {}", e.getCause());
    items = List.of(); // degrade gracefully
}

When it happens

Trigger: 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.

Common situations: Root deleted at runtime by an external process; permission changes after deployment; huge stores exhausting file descriptors; NFS stale handles.

Related errors

• Failed to clear file system store
• Failed to copy JAR file
• Failed to copy JAR files to working directory
• Failed to create root directory
• Failed to create temp directory for converter

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

Appendix: source

Thrown at spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/FileSystemStore.java:312

		List<StoreItem> items = new ArrayList<>();
		if (!Files.exists(rootPath)) {
			return items;
		}

		try {
			Files.walk(rootPath).filter(path -> path.toString().endsWith(".json")).forEach(path -> {
				try {
					String itemJson = Files.readString(path);
					StoreItem item = objectMapper.readValue(itemJson, StoreItem.class);
					items.add(item);
				}
				catch (Exception e) {
					// Skip invalid files
				}
			});
		}
		catch (IOException e) {
			throw new RuntimeException("Failed to scan file system for items", e);
		}

		return items;
	}

	/**
	 * Scan directories for namespaces.
	 * @param path current path
	 * @param currentNamespace current namespace path
	 * @param namespaceSet set to collect namespaces
	 * @param request namespace request
	 */
	private void scanDirectoriesForNamespaces(Path path, List<String> currentNamespace, Set<String> namespaceSet,
			NamespaceListRequest request) {
		try {
			if (!Files.exists(path) || !Files.isDirectory(path)) {
				return;
			}

View on GitHub (pinned to f82da0b50f)