{"record":{"id":"9abc4b4b576f6285","repo":"alibaba/spring-ai-alibaba","slug":"targetfolder-s-cannot-be-created","errorCode":null,"errorMessage":"targetFolder '%s' cannot be created","messagePattern":"targetFolder '(.+?)' cannot be created","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/file/FileSystemSaver.java","lineNumber":105,"sourceCode":"\t\tStateSerializer stateSerializer = builder.stateSerializer;\n\t\tif (stateSerializer == null) {\n\t\t\tthis.serializer = new CheckPointSerializer(StateGraph.DEFAULT_JACKSON_SERIALIZER);\n\t\t}\n\t\telse {\n\t\t\tthis.serializer = new CheckPointSerializer(stateSerializer);\n\t\t}\n\t\tthis.targetFolder = Objects.requireNonNull(builder.targetFolder, \"targetFolder cannot be null\");\n\t\tthis.maxCachedThreads = builder.maxCachedThreads;\n\t\tthis.latestCheckpointCache = createLatestCheckpointCache(builder.maxCachedThreads);\n\n\t\ttry {\n\t\t\tif (Files.exists(this.targetFolder) && !Files.isDirectory(this.targetFolder)) {\n\t\t\t\tthrow new IllegalArgumentException(format(\"targetFolder '%s' must be a directory\", this.targetFolder));\n\t\t\t}\n\t\t\tFiles.createDirectories(this.targetFolder);\n\t\t}\n\t\tcatch (IOException ex) {\n\t\t\tthrow new IllegalArgumentException(format(\"targetFolder '%s' cannot be created\", this.targetFolder), ex);\n\t\t}\n\n\t}\n\n\t/**\n\t * Creates a new builder for FileSystemSaver.\n\t * @return a new Builder instance\n\t */\n\tpublic static Builder builder() {\n\t\treturn new Builder();\n\t}\n\n\tprivate String getBaseName(RunnableConfig config) {\n\t\tvar threadId = config.threadId().orElse(THREAD_ID_DEFAULT);\n\t\treturn format(\"thread-%s\", threadId);\n\t}\n\n\tprivate Path getPath(RunnableConfig config) {","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/alibaba/spring-ai-alibaba/blob/f82da0b50f35744c13968191be2b1cd2452ef550/spring-ai-alibaba-graph-core/src/main/java/com/alibaba/cloud/ai/graph/checkpoint/savers/file/FileSystemSaver.java#L87-L123","documentation":"FileSystemSaver construction creates the targetFolder if missing via Files.createDirectories. If that fails with IOException (e.g. permission denied, parent is a file, disk error), it rethrows as IllegalArgumentException wrapping the original exception.","triggerScenarios":"Building a FileSystemSaver whose targetFolder does not exist and cannot be created: unwritable parent, parent path component is a file, or filesystem errors.","commonSituations":"Read-only containers/volumes, wrong user permissions, path collisions where a parent segment is an existing file, network mounts unavailable.","solutions":["Check the wrapped IOException cause for the real reason (permission, existence)","Create the directory manually and ensure write permissions for the process user","Verify no parent path component is an existing regular file","Run the app with a user that owns or can write to the target location"],"exampleFix":"// before\nFiles.setPosixFilePermissions(dir, PosixFilePermissions.fromString(\"r--------\"));\n// after\nFiles.createDirectories(dir);\nFiles.setPosixFilePermissions(dir, PosixFilePermissions.fromString(\"rwx------\"));","handlingStrategy":"validation","validationCode":"Files.createDirectories(targetFolder); // run and handle IOException before building the saver","typeGuard":"boolean canCreate(Path p) { Path parent = p.toAbsolutePath().getParent(); return parent != null && Files.isDirectory(parent) && Files.isWritable(parent); }","tryCatchPattern":"try { new FileSystemSaver(builder); } catch (IllegalArgumentException e) { handleCreateFailure(e.getCause()); }","preventionTips":["Verify volume writability before startup","Ensure parent path components are directories","Create the folder in deployment scripts with correct ownership"],"tags":["filesystem","checkpoint","permissions"],"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-14T11:17:12.474Z"}