aeron-io/aeron · error · ConfigurationException

AeronCluster.Context.clientName length must be <=…

Error message

AeronCluster.Context.clientName length must be <= <Aeron.Configuration.MAX_CLIENT_NAME_LENGTH>

What it means

The optional clientName identifies the cluster client and is carried in protocol fields, so its length is bounded by Aeron.Configuration.MAX_CLIENT_NAME_LENGTH. Context.conclude() throws ConfigurationException if a supplied clientName exceeds that bound.

Solutions

1. Shorten or truncate the client name to <= Aeron.Configuration.MAX_CLIENT_NAME_LENGTH characters
2. Pass null/default instead of an explicit clientName so the library generates one
3. Validate the name at config-load time and reject overly long values early

Example fix

// before
String name = InetAddress.getLocalHost().getHostName() + ".client-" + uuid;
ctx.clientName(name);
// after
String raw = InetAddress.getLocalHost().getHostName() + ".client-" + uuid;
ctx.clientName(raw.length() <= Aeron.Configuration.MAX_CLIENT_NAME_LENGTH
    ? raw : raw.substring(0, Aeron.Configuration.MAX_CLIENT_NAME_LENGTH));

String name = ...;
if (name != null && name.length() > Aeron.Configuration.MAX_CLIENT_NAME_LENGTH) {
    name = name.substring(0, Aeron.Configuration.MAX_CLIENT_NAME_LENGTH);
}
ctx.clientName(name);

When it happens

Trigger: Calling ctx.clientName(name) with name.length() > Aeron.Configuration.MAX_CLIENT_NAME_LENGTH (64) before connect().

Common situations: Deriving the client name from a hostname, pod name, or UUID string that exceeds the limit; using generated identifiers without truncation.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• AeronArchive.Context.messageRetryAttempts must be > 0, got:
• AeronCluster.Context ingressEndpoints must be null when…
• applicationSpecificFeedback length must be equal to
• clientLivenessTimeoutNs=
• clientName length must <=

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

Appendix: source

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

                        "AeronCluster.Context ingressEndpoints must be null when using IPC ingress");
                }
            }

            if (Strings.isEmpty(egressChannel))
            {
                throw new ConfigurationException("egressChannel must be specified");
            }

            final ChannelUri egressChannelUri = ChannelUri.parse(egressChannel);
            if (egressChannelUri.isUdp())
            {
                egressChannelUri.put(REJOIN_PARAM_NAME, "false");
                egressChannel = egressChannelUri.toString();
            }

            if (clientName.length() > Aeron.Configuration.MAX_CLIENT_NAME_LENGTH)
            {
                throw new ConfigurationException(
                    "AeronCluster.Context.clientName length must be <= " + Aeron.Configuration.MAX_CLIENT_NAME_LENGTH);
            }

            if (null == aeron)
            {
                aeron = Aeron.connect(
                    new Aeron.Context()
                        .aeronDirectoryName(aeronDirectoryName)
                        .errorHandler(errorHandler)
                        .subscriberErrorHandler(RethrowingErrorHandler.INSTANCE)
                        .clientName(clientName.isEmpty() ? "cluster-client" : clientName));

                ownsAeronClient = true;
            }

            if (null == idleStrategy)
            {
                idleStrategy = new BackoffIdleStrategy(1, 10, 1000, 1000);

View on GitHub (pinned to 6d60124e15)