{"record":{"id":"5fecfaede3f80684","repo":"alibaba/spring-ai-alibaba","slug":"failed-to-create-root-directory-rootpath","errorCode":null,"errorMessage":"Failed to create root directory: {rootPath}","messagePattern":"Failed to create root directory: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/FileSystemStore.java","lineNumber":245,"sourceCode":"\t@Override\n\tpublic long size() {\n\t\treturn getAllItems().size();\n\t}\n\n\t@Override\n\tpublic boolean isEmpty() {\n\t\treturn size() == 0;\n\t}\n\n\t/**\n\t * Initialize root directory.\n\t */\n\tprivate void initializeRootDirectory() {\n\t\ttry {\n\t\t\tFiles.createDirectories(rootPath);\n\t\t}\n\t\tcatch (IOException e) {\n\t\t\tthrow new RuntimeException(\"Failed to create root directory: \" + rootPath, e);\n\t\t}\n\t}\n\n\t/**\n\t * Create item path from namespace and key.\n\t * @param namespace namespace\n\t * @param key key\n\t * @return item path\n\t */\n\tprivate Path createItemPath(List<String> namespace, String key) {\n\t\tPath path = rootPath.toAbsolutePath().normalize();\n\t\tfor (String ns : namespace) {\n\t\t\tvalidatePathSegment(ns, \"namespace\");\n\t\t\tpath = path.resolve(ns);\n\t\t}\n\t\tvalidatePathSegment(key, \"key\");\n\t\tPath itemPath = path.resolve(key + \".json\").normalize();\n\t\tif (!itemPath.startsWith(rootPath.toAbsolutePath().normalize())) {","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/store/stores/FileSystemStore.java#L227-L263","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Verify the configured root path is not an existing regular file","Create parent directories manually or grant write permission on the parent","Point the store root to a writable location (e.g. under user home or tmp)","Run the application with a user that has write access to the target path"],"exampleFix":"// before\nstore = new FileSystemStore(\"/var/lib/agent-store\");\n// after\nPath root = Path.of(System.getProperty(\"user.home\"), \".agent-store\");\nFiles.createDirectories(root.getParent());\nstore = new FileSystemStore(root.toString());","handlingStrategy":"validation","validationCode":"Path root = Path.of(configuredRoot);\nif (Files.exists(root) && !Files.isDirectory(root)) {\n    throw new IllegalStateException(\"store root is a file, not a directory\");\n}\nif (!Files.isWritable(root.getParent() != null ? root.getParent() : root)) {\n    throw new IllegalStateException(\"cannot create store root: no write permission\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    store = new FileSystemStore(rootPath);\n} catch (RuntimeException e) {\n    throw new IllegalStateException(\"store init failed, check root path/permissions\", e);\n}","preventionTips":["Fail fast at startup by touching the root dir in a health check","Configure the root under a guaranteed-writable location","Do not point the root at an existing regular file"],"tags":["filesystem","io","initialization"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"f82da0b50f35744c13968191be2b1cd2452ef550","analyzedAt":"2026-09-09T15:32:42.421Z","contentChangedAt":"2026-09-09T15:32:42.421Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}