aeron-io/aeron · error · IllegalArgumentException

label length exceeds MAX_LABEL_LENGTH: <label.length()>

Error message

label length exceeds MAX_LABEL_LENGTH: <label.length()>

What it means

Thrown by ClientConductor's String-based addCounter overload when label.length() exceeds CountersManager.MAX_LABEL_LENGTH. Unlike the buffer overload this checks only the upper bound, since a String length cannot be negative.

Solutions

1. Truncate the label: label.length() > CountersManager.MAX_LABEL_LENGTH ? label.substring(0, MAX_LABEL_LENGTH) : label.
2. Use an abbreviated label and put the details in the counter key or external metadata.
3. Enforce a label length limit where labels are constructed.

Example fix

// before
client.addCounter(typeId, detailedLabel); // throws when > 1024 chars
// after
String label = detailedLabel.length() > CountersManager.MAX_LABEL_LENGTH
    ? detailedLabel.substring(0, CountersManager.MAX_LABEL_LENGTH)
    : detailedLabel;
client.addCounter(typeId, label);

if (label.length() > CountersManager.MAX_LABEL_LENGTH) label = label.substring(0, CountersManager.MAX_LABEL_LENGTH);
client.addCounter(typeId, label);

try { client.addCounter(typeId, label); } catch (IllegalArgumentException e) { log.error("counter label too long: {}", e.getMessage()); }

When it happens

Trigger: Calling addCounter(typeId, String label) with a label longer than CountersManager.MAX_LABEL_LENGTH (default 1024 characters).

Common situations: Labels embedding full channel URIs, session lists, or timestamps plus context; i18n strings longer than ASCII-size assumptions; telemetry systems auto-generating descriptive labels.

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

• key length out of bounds
• label length out of bounds
• counter id is negative
• counter id out of range: 0 - maxCounterId=
• existing max write time counter detected for archiveId=

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/ClientConductor.java:1165

            return (Counter)resourceByRegIdMap.get(registrationId);
        }
        finally
        {
            clientLock.unlock();
        }
    }

    Counter addCounter(final int typeId, final String label)
    {
        clientLock.lock();
        try
        {
            ensureActive();
            ensureNotReentrant();

            if (label.length() > CountersManager.MAX_LABEL_LENGTH)
            {
                throw new IllegalArgumentException("label length exceeds MAX_LABEL_LENGTH: " + label.length());
            }

            final long registrationId = driverProxy.addCounter(typeId, label);
            awaitResponse(registrationId);

            return (Counter)resourceByRegIdMap.get(registrationId);
        }
        finally
        {
            clientLock.unlock();
        }
    }

    Counter addStaticCounter(
        final int typeId,
        final DirectBuffer keyBuffer,
        final int keyOffset,
        final int keyLength,

View on GitHub (pinned to 6d60124e15)