alibaba/spring-ai-alibaba · error · RuntimeException

Failed to store item to file system

Error message

Failed to store item to file system

What it means

FileSystemStore.putItem() serializes the StoreItem to JSON and writes it to the item's file path under a write lock; any exception (Jackson serialization failure, IOException, missing parent directory) is wrapped in this RuntimeException. The write lock is released in finally.

Source

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

		this.objectMapper = new ObjectMapper();
		this.objectMapper.findAndRegisterModules();
		initializeRootDirectory();
	}

	@Override
	public void putItem(StoreItem item) {
		validatePutItem(item);

		lock.writeLock().lock();
		try {
			Path itemPath = createItemPath(item.getNamespace(), item.getKey());
			ensureDirectoryExists(itemPath.getParent());

			String itemJson = objectMapper.writeValueAsString(item);
			Files.write(itemPath, itemJson.getBytes());
		}
		catch (Exception e) {
			throw new RuntimeException("Failed to store item to file system", e);
		}
		finally {
			lock.writeLock().unlock();
		}
	}

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

View on GitHub (pinned to f82da0b50f)

Solutions

1. Check the chained cause to distinguish IOException (disk/permission) from Jackson serialization failure.
2. Verify the store root directory exists and the process has write permission.
3. Check free disk space and quota.
4. Ensure all values in the StoreItem are Jackson-serializable (no raw streams, non-POJOs).

Example fix

// before
Files.storeRoot = "/var/data/store"; // read-only mount
// after
Files.storeRoot = "/tmp/app-store"; // writable location, or chmod the dir

java.nio.file.Path root = storeRoot;
if (!java.nio.file.Files.isWritable(root)) {
    throw new IllegalStateException("Store root not writable: " + root);
}
if (root.toFile().getUsableSpace() < 10_000_000) {
    throw new IllegalStateException("Low disk space for store: " + root);
}

try { store.putItem(item); } catch (RuntimeException e) { log.error("put failed: {}", e.getCause(), e); /* check perms/disk or serialization */ }

When it happens

Trigger: Calling putItem when the storage root is not writable, the filesystem is full, the path is invalid/too long, or the item cannot be JSON-serialized.

Common situations: Read-only mounted volume or container filesystem; permission denied on the store directory; disk quota exceeded; non-serializable value objects in the StoreItem.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• Failed to delete item from 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/d54c40e588b6dbe7. Report an issue: GitHub.