{"record":{"id":"a9eb20989d5e3de9","repo":"aeron-io/aeron","slug":"failed-to-create-cluster-dir-clusterdir-getabsolutepath","errorCode":null,"errorMessage":"failed to create cluster dir: ${clusterDir.getAbsolutePath()}","messagePattern":"failed to create cluster dir: (.+?)","errorType":"exception","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackup.java","lineNumber":709,"sourceCode":"            }\n            else\n            {\n                clusterDirectoryName = clusterDir.getPath();\n            }\n\n            if (deleteDirOnStart)\n            {\n                IoUtil.delete(clusterDir, false);\n            }\n\n            if (null == catchupEndpoint)\n            {\n                throw new ClusterException(\"ClusterBackup.Context.catchupEndpoint must be set\");\n            }\n\n            if (!clusterDir.exists() && !clusterDir.mkdirs())\n            {\n                throw new ClusterException(\"failed to create cluster dir: \" + clusterDir.getAbsolutePath());\n            }\n\n            if (null == markFileDir)\n            {\n                final String dir = ClusteredServiceContainer.Configuration.markFileDir();\n                markFileDir = Strings.isEmpty(dir) ? clusterDir : new File(dir);\n            }\n\n            if (!markFileDir.exists() && !markFileDir.mkdirs())\n            {\n                throw new ArchiveException(\"failed to create mark file dir: \" + markFileDir.getAbsolutePath());\n            }\n\n            if (null == epochClock)\n            {\n                epochClock = SystemEpochClock.INSTANCE;\n            }\n","sourceCodeStart":691,"sourceCodeEnd":727,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackup.java#L691-L727","documentation":"ClusterBackup.Context.conclude() ensures the cluster directory exists. If the configured clusterDir does not exist and File.mkdirs() fails to create it, a ClusterException with the directory's absolute path is thrown. This typically reflects a filesystem permission or path problem, since mkdirs only fails when the OS refuses.","triggerScenarios":"Concluding a ClusterBackup.Context whose clusterDir (default from clusterDirectoryName, or set via clusterDir(File)) points to a location that cannot be created — missing parent with restrictive permissions, read-only filesystem, or a same-named file existing at the path.","commonSituations":"Running the backup agent as a non-root user without write access to the configured directory; container volume mounted read-only; clusterDirectoryName pointing inside a nonexistent, unwritable path.","solutions":["Check and fix filesystem permissions on the parent of the configured cluster dir so the process can create it.","Point clusterDir(...) at a writable location (or run the process with a user that owns the aeron cluster directory).","Ensure the path is not occupied by a regular file named like the directory; remove or rename it.","If in a container, ensure the mount is writable (not :ro) and the directory exists with correct ownership."],"exampleFix":"// before\nctx.clusterDir(new File(\"/proc/backup\")); // cannot mkdir there\n// after\nctx.clusterDir(new File(\"/var/lib/aeron/cluster-backup\")); // writable location","handlingStrategy":"validation","validationCode":"File dir = new File(clusterDirName);\nif (!dir.exists() && !dir.canWrite() && !dir.getParentFile().canWrite()) { throw new IllegalStateException(\"cannot create cluster dir: \" + dir); }","typeGuard":"static boolean clusterDirCreatable(File d) { return d.exists() ? d.isDirectory() : d.getParentFile() != null && d.getParentFile().canWrite(); }","tryCatchPattern":"try {\n    ctx.conclude();\n} catch (ClusterException e) {\n    if (e.getMessage().startsWith(\"failed to create cluster dir\")) { log.error(\"check permissions/path: {}\", e.getMessage()); }\n    throw e;\n}","preventionTips":["Pre-create the cluster dir with correct ownership in deployment scripts","Never place cluster dirs under read-only or /proc-like paths","Run the backup process as a user with write access to the Aeron directories"],"tags":["filesystem","directory","permissions","mkdir"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}