alibaba/spring-ai-alibaba · error · RuntimeException

Failed to retrieve item from file system

Error message

Failed to retrieve item from file system

What it means

FileSystemStore.getItem() reads the item file and deserializes it with Jackson, wrapping any exception in this RuntimeException under a read lock. It fires both when the file can't be read (missing/permission/IO) and when its JSON doesn't match StoreItem, even though 'item absent' is a normal condition.

Solutions

1. Check existence first or catch and treat NoSuchFileException as absent, since getItem may not return Optional.empty for missing files.
2. Inspect the chained cause: NoSuchFileException/AccessDeniedException vs JsonProcessingException to choose the fix.
3. Delete or repair corrupt JSON files in the store directory.
4. Migrate item files if a library upgrade changed the StoreItem format.

Example fix

// before
Optional<StoreItem> item = store.getItem(ns, key); // throws if absent
// after
Optional<StoreItem> item;
try {
    item = store.getItem(ns, key);
} catch (RuntimeException e) {
    if (e.getCause() instanceof NoSuchFileException) {
        item = Optional.empty();
    } else {
        throw e;
    }
}

java.nio.file.Path p = expectedItemPath(ns, key); // application-side path derivation
if (!java.nio.file.Files.exists(p)) return Optional.empty();

try { return store.getItem(ns, key); } catch (RuntimeException e) { if (e.getCause() instanceof java.nio.file.NoSuchFileException) return Optional.empty(); throw e; }

When it happens

Trigger: Calling getItem/profileItem/prefsItem for a key whose file doesn't exist (Files.readString throws NoSuchFileException), whose file has corrupt/hand-edited JSON, or with wrong file permissions.

Common situations: Looking up a never-stored item (expect Optional.empty but get this exception); files edited or truncated externally; library version upgrade changing StoreItem JSON shape; storage directory deleted while running.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Failed to deserialize store item
• Metadata must be an object
• Agent spec directory does not exist
• APP_COMPONENT_DETAIL_ERROR
• bytes cannot be empty

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/10ea04e0b9f4c7f3. 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:114

	}

	@Override
	public Optional<StoreItem> getItem(List<String> namespace, String key) {
		validateGetItem(namespace, key);

		lock.readLock().lock();
		try {
			Path itemPath = createItemPath(namespace, key);
			if (!Files.exists(itemPath)) {
				return Optional.empty();
			}

			String itemJson = Files.readString(itemPath);
			StoreItem item = objectMapper.readValue(itemJson, StoreItem.class);
			return Optional.of(item);
		}
		catch (Exception e) {
			throw new RuntimeException("Failed to retrieve item from file system", e);
		}
		finally {
			lock.readLock().unlock();
		}
	}

	@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;

View on GitHub (pinned to f82da0b50f)