{"record":{"id":"3dc33cbf259aa20f","repo":"aeron-io/aeron","slug":"encoded-principal-max-length-max-encoded-principal-length","errorCode":null,"errorMessage":"encoded principal max length ${MAX_ENCODED_PRINCIPAL_LENGTH} exceeded: length=${encodedPrincipal.length}","messagePattern":"encoded principal max length (.+?) exceeded: length=(.+?)","errorType":"validation","errorClass":"ClusterException","httpStatus":null,"severity":"error","filePath":"aeron-cluster/src/main/java/io/aeron/cluster/ClusterSession.java","lineNumber":541,"sourceCode":"            labelLength);\n    }\n\n    private static void logStateChange(\n        final int memberId,\n        final long sessionId,\n        final Action action,\n        final State oldState,\n        final State newState,\n        final String reason)\n    {\n        ClusterTracing.traceClusterSessionStateChange(memberId, sessionId, action, oldState, newState, reason);\n    }\n\n    static void checkEncodedPrincipalLength(final byte[] encodedPrincipal)\n    {\n        if (null != encodedPrincipal && encodedPrincipal.length > MAX_ENCODED_PRINCIPAL_LENGTH)\n        {\n            throw new ClusterException(\n                \"encoded principal max length \" + MAX_ENCODED_PRINCIPAL_LENGTH +\n                \" exceeded: length=\" + encodedPrincipal.length);\n        }\n    }\n\n    public String toString()\n    {\n        return \"ClusterSession{\" +\n            \"id=\" + id +\n            \", clusterMemberId=\" + clusterMemberId +\n            \", responseStreamId=\" + responseStreamId +\n            \", responseChannel='\" + responseChannel + '\\'' +\n            \", sessionInfo='\" + sessionInfo + '\\'' +\n            \", hasNewLeaderEventPending=\" + hasNewLeaderEventPending +\n            \", hasOpenEventPending=\" + hasOpenEventPending +\n            \", correlationId=\" + correlationId +\n            \", openedLogPosition=\" + openedLogPosition +\n            \", closedLogPosition=\" + closedLogPosition +","sourceCodeStart":523,"sourceCodeEnd":559,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-cluster/src/main/java/io/aeron/cluster/ClusterSession.java#L523-L559","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Shrink the principal credential: send a compact token/username instead of a full certificate or ticket.","Encode data efficiently (e.g. store large credentials out-of-band and reference them by an ID).","Check the credentials supplier/authenticator to confirm it truncates or encodes within the limit.","If you control the build, verify MAX_ENCODED_PRINCIPAL_LENGTH in ClusterSession before choosing credential sizes."],"exampleFix":"// before\nbyte[] principal = bigJwtToken.getBytes(UTF_8); // > 128 bytes\nsession.connect(..., principal);\n// after\nbyte[] principal = userIdClaim.getBytes(UTF_8); // keep it small\nsession.connect(..., principal);","handlingStrategy":"validation","validationCode":"// before connect\nbyte[] encodedPrincipal = encodePrincipal(credentials);\nif (encodedPrincipal != null && encodedPrincipal.length > 128) {\n    throw new IllegalArgumentException(\"principal credential too large: \" + encodedPrincipal.length);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep principal credentials under ~128 bytes: send a token or user id, not a full certificate.","Unit-test the credentials supplier with the intended auth payload sizes.","Check MAX_ENCODED_PRINCIPAL_LENGTH in your Aeron version before designing credentials."],"tags":["aeron","cluster","validation","limit-exceeded"],"backgroundTag":"payload-too-large","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}