alibaba/spring-ai-alibaba · error · RuntimeException

Failed to delete item from file system

Error message

Failed to delete item from file system

What it means

FileSystemStore.deleteItem wraps any exception during file deletion in a RuntimeException('Failed to delete item from file system'). The store deletes the JSON file backing a store item and then cleans up now-empty parent directories, all under a write lock. Any I/O or security failure in that sequence is rethrown with the original cause attached.

Source

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

	}

	@Override
	public boolean deleteItem(List<String> namespace, String key) {
		validateDeleteItem(namespace, key);

		lock.writeLock().lock();
		try {
			Path itemPath = createItemPath(namespace, key);
			if (Files.exists(itemPath)) {
				Files.delete(itemPath);
				// Clean up empty directories
				cleanupEmptyDirectories(itemPath.getParent());
				return true;
			}
			return false;
		}
		catch (Exception e) {
			throw new RuntimeException("Failed to delete item from file system", e);
		}
		finally {
			lock.writeLock().unlock();
		}
	}

	@Override
	public StoreSearchResult searchItems(StoreSearchRequest searchRequest) {
		validateSearchItems(searchRequest);

		lock.readLock().lock();
		try {
			List<StoreItem> allItems = getAllItems();

			// Apply filters
			List<StoreItem> filteredItems = allItems.stream()
				.filter(item -> matchesSearchCriteria(item, searchRequest))
				.collect(Collectors.toList());

View on GitHub (pinned to f82da0b50f)

Solutions

1. Inspect getCause() of the RuntimeException to see the underlying IOException
2. Check write permissions on the store root directory and the item file
3. Ensure no other process locks files under the store root
4. Point the store root to a writable path via configuration

Example fix

// before
store.deleteItem(List.of("agents"), "agent-1");
// after
try {
    store.deleteItem(List.of("agents"), "agent-1");
} catch (RuntimeException e) {
    log.error("delete failed", e.getCause());
}

java.nio.file.Path root = Path.of(storeRoot);
if (!Files.isWritable(root)) throw new IllegalStateException("store root not writable");

try {
    store.deleteItem(namespace, key);
} catch (RuntimeException e) {
    logger.error("delete failed: {}", e.getCause() == null ? e : e.getCause());
}

When it happens

Trigger: store.deleteItem(namespace, key) is called and Files.delete/cleanupEmptyDirectories throws: file locked by another process, read-only filesystem, insufficient permissions, or an IOException while walking/deleting parent dirs.

Common situations: Deploying on read-only container filesystems; another process (backup, antivirus) holding the JSON file open; running under a user lacking write permission on the store root; disk errors.

Related errors

• Failed to store item to file system
• Failed to clear file system store
• 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/6bde131156514bcf. Report an issue: GitHub.