aeron-io/aeron · error · ClusterException

encoded principal max length

Error message

encoded principal max length ${MAX_ENCODED_PRINCIPAL_LENGTH} exceeded: length=${encodedPrincipal.length}

What it means

ClusterSession.checkEncodedPrincipalLength enforces that the base64-encoded principal credential supplied with a session connect is at most MAX_ENCODED_PRINCIPAL_LENGTH bytes. Oversized principals are rejected to bound the size of session challenge/response data stored per session.

Solutions

1. Shrink the principal credential: send a compact token/username instead of a full certificate or ticket.
2. Encode data efficiently (e.g. store large credentials out-of-band and reference them by an ID).
3. Check the credentials supplier/authenticator to confirm it truncates or encodes within the limit.
4. If you control the build, verify MAX_ENCODED_PRINCIPAL_LENGTH in ClusterSession before choosing credential sizes.

Example fix

// before
byte[] principal = bigJwtToken.getBytes(UTF_8); // > 128 bytes
session.connect(..., principal);
// after
byte[] principal = userIdClaim.getBytes(UTF_8); // keep it small
session.connect(..., principal);

// before connect
byte[] encodedPrincipal = encodePrincipal(credentials);
if (encodedPrincipal != null && encodedPrincipal.length > 128) {
    throw new IllegalArgumentException("principal credential too large: " + encodedPrincipal.length);
}

When it happens

Trigger: Calling connect on a ClusterSession (directly or via the cluster client authentication path) with an encodedPrincipal byte array whose length exceeds MAX_ENCODED_PRINCIPAL_LENGTH (typically 128).

Common situations: Applications embedding large certificates, JWTs or Kerberos tickets into the principal credential instead of a compact token or reference; a credentials supplier returning the whole token blob rather than an identifier.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Related errors

• segment file length not a power of 2
• segment file length not in valid range
• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• URI length ( ) exceeds max supported length ( )…
• unknown media

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

Appendix: source

Thrown at aeron-cluster/src/main/java/io/aeron/cluster/ClusterSession.java:541

            labelLength);
    }

    private static void logStateChange(
        final int memberId,
        final long sessionId,
        final Action action,
        final State oldState,
        final State newState,
        final String reason)
    {
        ClusterTracing.traceClusterSessionStateChange(memberId, sessionId, action, oldState, newState, reason);
    }

    static void checkEncodedPrincipalLength(final byte[] encodedPrincipal)
    {
        if (null != encodedPrincipal && encodedPrincipal.length > MAX_ENCODED_PRINCIPAL_LENGTH)
        {
            throw new ClusterException(
                "encoded principal max length " + MAX_ENCODED_PRINCIPAL_LENGTH +
                " exceeded: length=" + encodedPrincipal.length);
        }
    }

    public String toString()
    {
        return "ClusterSession{" +
            "id=" + id +
            ", clusterMemberId=" + clusterMemberId +
            ", responseStreamId=" + responseStreamId +
            ", responseChannel='" + responseChannel + '\'' +
            ", sessionInfo='" + sessionInfo + '\'' +
            ", hasNewLeaderEventPending=" + hasNewLeaderEventPending +
            ", hasOpenEventPending=" + hasOpenEventPending +
            ", correlationId=" + correlationId +
            ", openedLogPosition=" + openedLogPosition +
            ", closedLogPosition=" + closedLogPosition +

View on GitHub (pinned to 6d60124e15)