aeron-io/aeron · error · ConfigurationException

clientName length must <=

Error message

clientName length must <= <MAX_CLIENT_NAME_LENGTH>

What it means

Aeron.Context throws this ConfigurationException when the configured clientName exceeds MAX_CLIENT_NAME_LENGTH. The client name is sent to the media driver and recorded (e.g. in the C' file), so it is bounded; an over-long name is treated as a configuration error at connect time.

Solutions

1. Truncate or hash the client name so its length is <= MAX_CLIENT_NAME_LENGTH before calling ctx.clientName(...)
2. Use a compact unique identifier (e.g. UUID prefix or hash of the long name)
3. Validate the name length at startup and fail fast with your own clearer message

Example fix

// before
ctx.clientName(host + "-" + longJobId + "-" + region); // may exceed limit
// after
String name = host + "-" + Integer.toHexString(longJobId.hashCode());
if (name.length() > Aeron.Context.MAX_CLIENT_NAME_LENGTH) {
    name = name.substring(0, Aeron.Context.MAX_CLIENT_NAME_LENGTH);
}
ctx.clientName(name);

if (name.length() > Aeron.Context.MAX_CLIENT_NAME_LENGTH) { name = name.substring(0, Aeron.Context.MAX_CLIENT_NAME_LENGTH); }

String safeClientName(String s) { return s == null ? s : (s.length() <= Aeron.Context.MAX_CLIENT_NAME_LENGTH ? s : s.substring(0, Aeron.Context.MAX_CLIENT_NAME_LENGTH)); }

try { ctx.clientName(name); } catch (ConfigurationException e) { if (e.getMessage().startsWith("clientName length")) { ctx.clientName(safeClientName(name)); } else throw e; }

When it happens

Trigger: Calling ctx.clientName(name) with a string whose length() is greater than Aeron.Context.MAX_CLIENT_NAME_LENGTH (effectively 100, being MAX_HOST_NAME_LEN 255-derived — check the constant; the message embeds the actual limit), then Aeron.connect(ctx).

Common situations: Generating client names from host+process+timestamp concatenations that exceed the limit; embedding long job IDs or URIs into the client name; configurations built for other systems with looser name limits.

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.clientName length must be <=…
• AeronCluster.Context ingressEndpoints must be null when…
• applicationSpecificFeedback length must be equal to
• clientLivenessTimeoutNs=

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/Aeron.java:1198

                clientLock = new ReentrantLock();
            }
            else if (clientLock instanceof NoOpLock && !useConductorAgentInvoker)
            {
                throw new ConfigurationException(
                    "Must use Aeron.Context.useConductorAgentInvoker(true) when Aeron.Context.clientLock(...) " +
                    "is using a NoOpLock");
            }

            if (null != driverAgentInvoker && !useConductorAgentInvoker)
            {
                throw new ConfigurationException(
                    "Must use Aeron.Context.useConductorAgentInvoker(true) when Aeron.Context.driverAgentInvoker() " +
                    "is set");
            }

            if (clientName.length() > MAX_CLIENT_NAME_LENGTH)
            {
                throw new ConfigurationException("clientName length must <= " + MAX_CLIENT_NAME_LENGTH);
            }

            if (null == epochClock)
            {
                epochClock = SystemEpochClock.INSTANCE;
            }

            if (null == nanoClock)
            {
                nanoClock = SystemNanoClock.INSTANCE;
            }

            if (idleSleepDurationNs < 0 || idleSleepDurationNs > TimeUnit.SECONDS.toNanos(1))
            {
                throw new ConfigurationException("Invalid idle sleep duration: " + idleSleepDurationNs + "ns");
            }

            if (null == idleStrategy)

View on GitHub (pinned to 6d60124e15)