aeron-io/aeron · error · IllegalArgumentException

key length out of bounds

Error message

key length out of bounds: <keyLength>

What it means

Thrown by ClientConductor.addCounter when the provided key length is negative or exceeds CountersManager.MAX_KEY_LENGTH. Counter keys live in a fixed-size buffer managed by the counters manager, so out-of-bounds lengths cannot be represented.

Solutions

1. Shrink the key payload so keyLength <= CountersManager.MAX_KEY_LENGTH.
2. Fix keyOffset/keyLength computation and validate 0 <= keyLength before calling.
3. Store large metadata externally and keep only a small id/handle in the key.

Example fix

// before
int keyLength = serialized.length; // may exceed CountersManager.MAX_KEY_LENGTH
client.addCounter(typeId, keyBuffer, 0, keyLength, labelBuffer, 0, labelLength);
// after
int keyLength = Math.min(serialized.length, CountersManager.MAX_KEY_LENGTH); // or validate and fail with your own message
if (serialized.length > CountersManager.MAX_KEY_LENGTH) throw new IllegalStateException("counter key too large");

if (keyLength < 0 || keyLength > CountersManager.MAX_KEY_LENGTH) throw new IllegalArgumentException("keyLength=" + keyLength);
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 key invalid: {}", e.getMessage()); }

When it happens

Trigger: Calling addCounter(typeId, keyBuffer, keyOffset, keyLength, labelBuffer, labelOffset, labelLength) with keyLength < 0 or keyLength > CountersManager.MAX_KEY_LENGTH (also keyOffset+keyLength overflowing the provided buffer).

Common situations: Serializing a custom metadata object into the key buffer larger than the max key length; passing buffer.remaining() where the offset was wrong; uninitialized length variables defaulting oddly or computed as negative.

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

• label 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/ead27b5e788e0237. Report an issue: GitHub.

Appendix: source

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

    Counter addCounter(
        final int typeId,
        final DirectBuffer keyBuffer,
        final int keyOffset,
        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();
        }

View on GitHub (pinned to 6d60124e15)