aeron-io/aeron · error · IllegalArgumentException

label length out of bounds

Error message

label length out of bounds: <labelLength>

What it means

Thrown by ClientConductor.addCounter when the label length is negative or exceeds CountersManager.MAX_LABEL_LENGTH. Labels are stored in fixed-size slots in the counters file, so oversized labels cannot be registered.

Solutions

1. Truncate the label to CountersManager.MAX_LABEL_LENGTH characters/bytes before calling addCounter.
2. Shorten the label template (drop redundant prefixes such as 'counter for channel ...').
3. Validate label length at configuration time and fail with your own clearer error.

Example fix

// before
String label = "flow rate for " + uri + " stream " + streamId + " ..."; // may exceed limit
client.addCounter(typeId, label);
// after
String label = shortLabel(uri, streamId);
if (label.length() > CountersManager.MAX_LABEL_LENGTH) label = label.substring(0, CountersManager.MAX_LABEL_LENGTH);
client.addCounter(typeId, label);

if (labelLength < 0 || labelLength > CountersManager.MAX_LABEL_LENGTH) labelLength = CountersManager.MAX_LABEL_LENGTH; // truncate
client.addCounter(typeId, keyBuffer, keyOffset, keyLength, labelBuffer, labelOffset, labelLength);

try { client.addCounter(typeId, keyBuffer, keyOffset, keyLength, labelBuffer, labelOffset, labelLength); } catch (IllegalArgumentException e) { log.error("counter label invalid: {}", e.getMessage()); }

When it happens

Trigger: Calling the buffer-based addCounter with labelLength < 0 or labelLength > CountersManager.MAX_LABEL_LENGTH (default 1024), typically labelBytes.length beyond the limit.

Common situations: Generating human-readable labels that include long URIs or identifiers; unbounded label construction from user input; dynamic labels concatenating many fields.

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 exceeds MAX_LABEL_LENGTH: <label.length()>
• 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/64b1256fceb0347f. Report an issue: GitHub.

Appendix: source

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

        final int keyLength,
        final DirectBuffer labelBuffer,
        final int labelOffset,
        final int labelLength)
    {
        clientLock.lock();
        try
        {
            ensureActive();
            ensureNotReentrant();

            if (keyLength < 0 || keyLength > CountersManager.MAX_KEY_LENGTH)
            {
                throw new IllegalArgumentException("key length out of bounds: " + keyLength);
            }

            if (labelLength < 0 || labelLength > CountersManager.MAX_LABEL_LENGTH)
            {
                throw new IllegalArgumentException("label length out of bounds: " + labelLength);
            }

            final long registrationId = driverProxy.addCounter(
                typeId, keyBuffer, keyOffset, keyLength, labelBuffer, labelOffset, labelLength);

            awaitResponse(registrationId);

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

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

View on GitHub (pinned to 6d60124e15)