What causes " " in aeron-io/aeron?

Read the exception message (egressPoller.detail()) — it states the cluster-side cause; fix that on the cluster or client

aeron-io/aeron · error · ClusterException

<egressPoller.detail()>

Error message

<egressPoller.detail()>

What it means

While polling the egress subscription during connect(), the EgressPoller may report an ERROR event from the cluster (e.g. session rejected or authentication/consensus failure). AeronCluster propagates the poller's detail string as a ClusterException, so connect fails with the cluster's own error description.

Solutions

Read the exception message (egressPoller.detail()) — it states the cluster-side cause; fix that on the cluster or client
Ensure the cluster has an elected leader and services are caught up before connecting clients
Check cluster session limits and authentication configuration (Context.credentials() / authenticator server-side)
Retry connect after the cluster recovers from election/replay

Example fix

// before
AeronCluster cluster = AeronCluster.connect(ctx); // ClusterException: <cluster detail>
// after
try {
    AeronCluster cluster = AeronCluster.connect(ctx);
} catch (ClusterException e) {
    LOG.error("Cluster rejected connect: " + e.getMessage()); // act on cluster-side detail
    throw e;
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
    AeronCluster cluster = AeronCluster.connect(ctx);
} catch (ClusterException e) {
    LOG.error("Cluster rejected connect: {}", e.getMessage());
    // branch on detail: wait for leader, fix auth credentials, or honor session limits
    throw e;
}

Prevention

Wait for the cluster to have an elected leader before connecting clients
Ensure client credentials match the cluster's authenticator configuration
Respect max session limits; close idle sessions before opening new ones
Log egressPoller.detail() server-side cause and alert on repeated rejections

When it happens

Trigger: EgressPoller transitions to State.ERROR during connect, typically because the cluster rejected the connect request (invalid session, cluster unavailable for service, auth failure) and sent an error detail back.

Common situations: Client connecting while the cluster has no leader or is in election; max sessions reached; authentication rejected (different credentials than expected); snapshot/consensus issues on the cluster side.

Related errors

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

Appendix: source

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

                    correlationId = NULL_VALUE;
                    clusterSessionId = egressPoller.clusterSessionId();
                    prepareChallengeResponse(ctx.credentialsSupplier().onChallenge(egressPoller.encodedChallenge()));
                    return;
                }

                switch (egressPoller.eventCode())
                {
                    case OK:
                        leadershipTermId = egressPoller.leadershipTermId();
                        leaderMemberId = egressPoller.leaderMemberId();
                        clusterSessionId = egressPoller.clusterSessionId();
                        leaderHeartbeatTimeoutNs = egressPoller.leaderHeartbeatTimeoutNs();
                        egressImage = egressPoller.egressImage();
                        state(State.CONCLUDE_CONNECT);
                        break;

                    case ERROR:
                        throw new ClusterException(egressPoller.detail());

                    case REDIRECT:
                        updateMembers();
                        break;

                    case AUTHENTICATION_REJECTED:
                        throw new AuthenticationException(egressPoller.detail());

                    case CLOSED:
                    case NULL_VAL:
                        break;
                }
            }
        }

        private void prepareChallengeResponse(final byte[] encodedCredentials)
        {
            correlationId = ctx.aeron().nextCorrelationId();

View on GitHub (pinned to 6d60124e15)