alibaba/spring-ai-alibaba · error · RuntimeException

Failed to clear file system store

Error message

Failed to clear file system store

What it means

FileSystemStore.clear removes the entire root directory recursively and re-creates it; any exception in that process is wrapped in RuntimeException('Failed to clear file system store'). It runs under the store write lock, so a failure leaves the store unchanged but propagates to the caller.

Source

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

			int endIndex = Math.min(offset + limit, namespaces.size());
			return namespaces.subList(offset, endIndex);
		}
		finally {
			lock.readLock().unlock();
		}
	}

	@Override
	public void clear() {
		lock.writeLock().lock();
		try {
			if (Files.exists(rootPath)) {
				deleteDirectoryRecursively(rootPath);
			}
			initializeRootDirectory();
		}
		catch (Exception e) {
			throw new RuntimeException("Failed to clear file system store", e);
		}
		finally {
			lock.writeLock().unlock();
		}
	}

	@Override
	public long size() {
		return getAllItems().size();
	}

	@Override
	public boolean isEmpty() {
		return size() == 0;
	}

	/**
	 * Initialize root directory.

View on GitHub (pinned to f82da0b50f)

Solutions

1. Check the wrapped cause for the specific file that failed to delete
2. Verify the process has delete permissions on every entry under the store root
3. Manually remove leftover files then retry clear()
4. Move the store root to a local writable filesystem

Example fix

// before
store.clear();
// after
try {
    store.clear();
} catch (RuntimeException e) {
    log.error("store clear failed: {}", e.getCause().getMessage());
}

if (!Files.isWritable(Path.of(storeRoot))) {
    throw new IllegalStateException("store root not writable, clear() will fail");
}

try {
    store.clear();
} catch (RuntimeException e) {
    logger.error("clear failed: {}", e.getCause());
    // leave store intact, alert operator
}

When it happens

Trigger: store.clear() is called and deleteDirectoryRecursively(rootPath) or Files.exists/initializeRootDirectory throws IOException — e.g. a file under root cannot be deleted, or the root cannot be recreated after deletion.

Common situations: Clearing a store mounted on a read-only or full disk; permission mismatch after the root dir was created by another user; NFS/Windows locking a file during recursive delete.

Related errors

• Failed to store item to file system
• Failed to delete item from file system
• Got error when creating files
• Got error when creating files
• Failed to create temp directory for converter

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