aeron-io/aeron · error · IllegalArgumentException

counter id out of range: 0 - maxCounterId=

Error message

counter id <counterId> out of range: 0 - maxCounterId=<maxCounterId>

What it means

validateCounterId also enforces an upper bound: counterId must be <= (metadataBuffer.capacity() / METADATA_LENGTH) - 1. This error means the id points past the last counter slot in the counters metadata buffer, i.e. it cannot exist in this Aeron media driver's counter space.

Solutions

1. Check counterId against the max: (countersMetaDataBuffer.capacity() / METADATA_LENGTH) - 1 before the call.
2. Allocate the counter through Aeron/CounterManager so you always hold a valid id instead of hardcoding one.
3. If ids come from another driver, re-map them to this driver's allocated counters.
4. Increase the driver's counters metadata capacity if you legitimately need more counters.

Example fix

// before
int id = 5000; // arbitrary
aeron.counters().updateLabel(id, "x");
// after
int maxCounterId = (metaDataBuffer.capacity() / METADATA_LENGTH) - 1;
if (id >= 0 && id <= maxCounterId) {
    aeron.counters().updateLabel(id, "x");
}

int maxCounterId = (metaDataBuffer.capacity() / METADATA_LENGTH) - 1;
if (counterId < 0 || counterId > maxCounterId) throw new IllegalArgumentException("counterId out of range");

try {
    aeronCounters.updateLabel(counterId, label);
} catch (IllegalArgumentException e) {
    log.warn("counter id beyond driver counter space", e);
}

When it happens

Trigger: Passing a counterId larger than the driver's configured max counters (MAX_COUNTERS / counters metadata buffer capacity) to any AeronCounters API that validates ids.

Common situations: Driver configured with a smaller counters buffer than a hardcoded id assumes; ids from another driver/session reused against a new Aeron instance; misunderstanding that valid range is 0..maxCounterId inclusive.

Related errors

• counter id is negative
• counter id is not allocated, state
• initialCapacity outside range 0
• limit outside range: capacity=
• key length out of bounds

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

Appendix: source

Thrown at aeron-client/src/main/java/io/aeron/AeronCounters.java:1668

    {
        Objects.requireNonNull(metaDataBuffer);
        Objects.requireNonNull(valuesBuffer);
        validateCounterId(metaDataBuffer, counterId);

        valuesBuffer.putLongRelease(counterOffset(counterId) + REFERENCE_ID_OFFSET, referenceId);
    }

    private static void validateCounterId(final AtomicBuffer metaDataBuffer, final int counterId)
    {
        if (counterId < 0)
        {
            throw new IllegalArgumentException("counter id " + counterId + " is negative");
        }

        final int maxCounterId = (metaDataBuffer.capacity() / METADATA_LENGTH) - 1;
        if (counterId > maxCounterId)
        {
            throw new IllegalArgumentException(
                "counter id " + counterId + " out of range: 0 - maxCounterId=" + maxCounterId);
        }
    }
}

View on GitHub (pinned to 6d60124e15)