aeron-io/aeron · error · ClusterException

ClusterBackup.Context.catchupEndpoint must be set

Error message

ClusterBackup.Context.catchupEndpoint must be set

What it means

During ClusterBackup.Context.conclude(), the catchupEndpoint property is mandatory — the backup client must know where to request a catchup replay from the cluster. If it was never set via catchupEndpoint(...), conclude() throws this ClusterException before starting anything.

Solutions

1. Call catchupEndpoint("host:port") on the ClusterBackup.Context before conclude(), pointing at a cluster member's catchup listener.
2. Set the equivalent system property / configuration value (aeron.cluster.backup.catchup.endpoint) if using property-based configuration.
3. Verify the endpoint matches one actually bound by the cluster member's backup/catchup server.

Example fix

// before
ClusterBackup.Context ctx = new ClusterBackup.Context(); // no catchupEndpoint
// after
ClusterBackup.Context ctx = new ClusterBackup.Context()
    .catchupEndpoint("localhost:9010");

if (ctx instanceof ClusterBackup.Context c && c.catchupEndpoint() == null) { throw new IllegalArgumentException("catchupEndpoint required"); }

static boolean catchupEndpointSet(ClusterBackup.Context ctx) { return ctx.catchupEndpoint() != null; }

try {
    ctx.conclude();
} catch (ClusterException e) {
    if (e.getMessage().contains("catchupEndpoint")) { log.error("set ClusterBackup.Context.catchupEndpoint before conclude"); }
    throw e;
}

When it happens

Trigger: Building a ClusterBackup Context without calling ClusterBackup.Context.catchupEndpoint(String) and then concluding/starting the ClusterBackup.

Common situations: New users of the cluster backup API omitting the required endpoint (e.g. 'localhost:9010' style host:port of a cluster member); migrating from older Aeron versions where it defaulted from other configuration.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• recordingId must be set
• liveStreamId must be set
• local archive control must be IPC
• replicationChannel must be set
• service count must be zero when ConsensusModuleExtension is…

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

Appendix: source

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

            }

            if (null == clusterDir)
            {
                clusterDir = new File(clusterDirectoryName);
            }
            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());
            }

View on GitHub (pinned to 6d60124e15)