aeron-io/aeron · error · ClusterException

failed to create cluster dir

Error message

failed to create cluster dir: ${clusterDir.getAbsolutePath()}

What it means

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.

Solutions

1. Check and fix filesystem permissions on the parent of the configured cluster dir so the process can create it.
2. Point clusterDir(...) at a writable location (or run the process with a user that owns the aeron cluster directory).
3. Ensure the path is not occupied by a regular file named like the directory; remove or rename it.
4. If in a container, ensure the mount is writable (not :ro) and the directory exists with correct ownership.

Example fix

// before
ctx.clusterDir(new File("/proc/backup")); // cannot mkdir there
// after
ctx.clusterDir(new File("/var/lib/aeron/cluster-backup")); // writable location

File dir = new File(clusterDirName);
if (!dir.exists() && !dir.canWrite() && !dir.getParentFile().canWrite()) { throw new IllegalStateException("cannot create cluster dir: " + dir); }

static boolean clusterDirCreatable(File d) { return d.exists() ? d.isDirectory() : d.getParentFile() != null && d.getParentFile().canWrite(); }

try {
    ctx.conclude();
} catch (ClusterException e) {
    if (e.getMessage().startsWith("failed to create cluster dir")) { log.error("check permissions/path: {}", e.getMessage()); }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

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 mark file dir
• failed to write recording
• <IOException message>
• unable to create node-state file
• UncheckedIOException while backing up recording log

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/a9eb20989d5e3de9. Report an issue: GitHub.

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ClusterBackup.java:709

            }
            else
            {
                clusterDirectoryName = clusterDir.getPath();
            }

            if (deleteDirOnStart)
            {
                IoUtil.delete(clusterDir, false);
            }

            if (null == catchupEndpoint)
            {
                throw new ClusterException("ClusterBackup.Context.catchupEndpoint must be set");
            }

            if (!clusterDir.exists() && !clusterDir.mkdirs())
            {
                throw new ClusterException("failed to create cluster dir: " + clusterDir.getAbsolutePath());
            }

            if (null == markFileDir)
            {
                final String dir = ClusteredServiceContainer.Configuration.markFileDir();
                markFileDir = Strings.isEmpty(dir) ? clusterDir : new File(dir);
            }

            if (!markFileDir.exists() && !markFileDir.mkdirs())
            {
                throw new ArchiveException("failed to create mark file dir: " + markFileDir.getAbsolutePath());
            }

            if (null == epochClock)
            {
                epochClock = SystemEpochClock.INSTANCE;
            }

View on GitHub (pinned to 6d60124e15)