aeron-io/aeron · error · ClusterException

unexpected loss of connection to cluster

Error message

unexpected loss of connection to cluster

What it means

During connect()'s AWAIT_CONNECTED/SEND state, the client publishes a connect request and checks the publication position. If the publication returns CLOSED or NOT_CONNECTED the client's publication is dead, so connect aborts with ClusterException('unexpected loss of connection to cluster').

Solutions

  1. Verify cluster members are running and ingressEndpoints/ingressChannel point at live nodes
  2. Check MediaDriver is running and Aeron directories are healthy; restart driver and client
  3. Retry AeronCluster.connect() with backoff; add retransient connect logic around bootstrap
  4. Inspect cluster node logs and ingress endpoint configuration for mismatched endpoints

Example fix

// before
AeronCluster cluster = AeronCluster.connect(ctx); // fails if cluster temporarily down
// after
AeronCluster cluster = null;
for (int i = 0; i < 5 && cluster == null; i++) {
    try { cluster = AeronCluster.connect(ctx); }
    catch (ClusterException e) { sleepBackoff(i); }
}
Defensive patterns

Strategy: retry

Validate before calling

// before connecting, sanity-check ingress endpoints resolve
for (String ep : ingressEndpoints.split(",")) { /* verify host:port reachable */ }

Try / catch

try {
    AeronCluster cluster = AeronCluster.connect(ctx);
} catch (ClusterException e) {
    if (e.getMessage().contains("unexpected loss of connection")) {
        // retry with backoff after checking cluster/driver health
    } else {
        throw e;
    }
}

Prevention

When it happens

Trigger: The ingress publication closes because the cluster is down/unreachable, ingressEndpoints are wrong, or the destination died after the client started connecting.

Common situations: Cluster nodes not running or wrong ingress endpoint/port; firewall or network drop; cluster leader change during connect leaving the publication closed; driver (MediaDriver) restarted mid-connect.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/client/AeronCluster.java:2482

                .version(Configuration.PROTOCOL_SEMANTIC_VERSION)
                .responseChannel(responseChannel)
                .putEncodedCredentials(encodedCredentials, 0, encodedCredentials.length)
                .clientInfo(clientInfo);

            messageLength = MessageHeaderEncoder.ENCODED_LENGTH + encoder.encodedLength();
            state(State.SEND_MESSAGE);
        }

        private void sendMessage()
        {
            final long position = ingressPublication.offer(buffer, 0, messageLength);
            if (position > 0)
            {
                state(State.POLL_RESPONSE);
            }
            else if (Publication.CLOSED == position || Publication.NOT_CONNECTED == position)
            {
                throw new ClusterException("unexpected loss of connection to cluster");
            }
        }

        private void pollResponse()
        {
            if (egressPoller.poll() > 0 &&
                egressPoller.isPollComplete() &&
                egressPoller.correlationId() == correlationId)
            {
                if (egressPoller.isChallenged())
                {
                    correlationId = NULL_VALUE;
                    clusterSessionId = egressPoller.clusterSessionId();
                    prepareChallengeResponse(ctx.credentialsSupplier().onChallenge(egressPoller.encodedChallenge()));
                    return;
                }

                switch (egressPoller.eventCode())

View on GitHub (pinned to 6d60124e15)