alibaba/spring-ai-alibaba · critical · RuntimeException

Failed to create root directory: {rootPath}

Error message

Failed to create root directory: {rootPath}

What it means

FileSystemStore.initializeRootDirectory creates the store root with Files.createDirectories and wraps IOException in RuntimeException('Failed to create root directory: <path>'). It runs during construction and after clear(), so a failure here prevents the store from being usable at all.

Source

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

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

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

	/**
	 * Initialize root directory.
	 */
	private void initializeRootDirectory() {
		try {
			Files.createDirectories(rootPath);
		}
		catch (IOException e) {
			throw new RuntimeException("Failed to create root directory: " + rootPath, e);
		}
	}

	/**
	 * Create item path from namespace and key.
	 * @param namespace namespace
	 * @param key key
	 * @return item path
	 */
	private Path createItemPath(List<String> namespace, String key) {
		Path path = rootPath.toAbsolutePath().normalize();
		for (String ns : namespace) {
			validatePathSegment(ns, "namespace");
			path = path.resolve(ns);
		}
		validatePathSegment(key, "key");
		Path itemPath = path.resolve(key + ".json").normalize();
		if (!itemPath.startsWith(rootPath.toAbsolutePath().normalize())) {

View on GitHub (pinned to f82da0b50f)

Solutions

1. Verify the configured root path is not an existing regular file
2. Create parent directories manually or grant write permission on the parent
3. Point the store root to a writable location (e.g. under user home or tmp)
4. Run the application with a user that has write access to the target path

Example fix

// before
store = new FileSystemStore("/var/lib/agent-store");
// after
Path root = Path.of(System.getProperty("user.home"), ".agent-store");
Files.createDirectories(root.getParent());
store = new FileSystemStore(root.toString());

Path root = Path.of(configuredRoot);
if (Files.exists(root) && !Files.isDirectory(root)) {
    throw new IllegalStateException("store root is a file, not a directory");
}
if (!Files.isWritable(root.getParent() != null ? root.getParent() : root)) {
    throw new IllegalStateException("cannot create store root: no write permission");
}

try {
    store = new FileSystemStore(rootPath);
} catch (RuntimeException e) {
    throw new IllegalStateException("store init failed, check root path/permissions", e);
}

When it happens

Trigger: Constructing FileSystemStore with a root path whose parent does not exist and cannot be created (missing parent, permission denied, path is an existing regular file, or filesystem is read-only).

Common situations: Configuring the store root as '/var/lib/store' without root privileges; pointing root at an existing file instead of a directory; read-only container filesystems; typoed config path causing creation attempts in forbidden locations.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• Failed to create temp directory for converter
• Got error when creating files
• Got error when creating files
• SKILL.md not found at: {}
• Failed to store item to file system

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