{"record":{"id":"c61a048b1defcd12","repo":"aeron-io/aeron","slug":"counter-id-counterid-out-of-range-0-maxcounterid","errorCode":null,"errorMessage":"counter id <counterId> out of range: 0 - maxCounterId=<maxCounterId>","messagePattern":"counter id <counterId> out of range: 0 - maxCounterId=<maxCounterId>","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/AeronCounters.java","lineNumber":1668,"sourceCode":"    {\n        Objects.requireNonNull(metaDataBuffer);\n        Objects.requireNonNull(valuesBuffer);\n        validateCounterId(metaDataBuffer, counterId);\n\n        valuesBuffer.putLongRelease(counterOffset(counterId) + REFERENCE_ID_OFFSET, referenceId);\n    }\n\n    private static void validateCounterId(final AtomicBuffer metaDataBuffer, final int counterId)\n    {\n        if (counterId < 0)\n        {\n            throw new IllegalArgumentException(\"counter id \" + counterId + \" is negative\");\n        }\n\n        final int maxCounterId = (metaDataBuffer.capacity() / METADATA_LENGTH) - 1;\n        if (counterId > maxCounterId)\n        {\n            throw new IllegalArgumentException(\n                \"counter id \" + counterId + \" out of range: 0 - maxCounterId=\" + maxCounterId);\n        }\n    }\n}\n","sourceCodeStart":1650,"sourceCodeEnd":1673,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/AeronCounters.java#L1650-L1673","documentation":"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.","triggerScenarios":"Passing a counterId larger than the driver's configured max counters (MAX_COUNTERS / counters metadata buffer capacity) to any AeronCounters API that validates ids.","commonSituations":"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.","solutions":["Check counterId against the max: (countersMetaDataBuffer.capacity() / METADATA_LENGTH) - 1 before the call.","Allocate the counter through Aeron/CounterManager so you always hold a valid id instead of hardcoding one.","If ids come from another driver, re-map them to this driver's allocated counters.","Increase the driver's counters metadata capacity if you legitimately need more counters."],"exampleFix":"// before\nint id = 5000; // arbitrary\naeron.counters().updateLabel(id, \"x\");\n// after\nint maxCounterId = (metaDataBuffer.capacity() / METADATA_LENGTH) - 1;\nif (id >= 0 && id <= maxCounterId) {\n    aeron.counters().updateLabel(id, \"x\");\n}","handlingStrategy":"validation","validationCode":"int maxCounterId = (metaDataBuffer.capacity() / METADATA_LENGTH) - 1;\nif (counterId < 0 || counterId > maxCounterId) throw new IllegalArgumentException(\"counterId out of range\");","typeGuard":null,"tryCatchPattern":"try {\n    aeronCounters.updateLabel(counterId, label);\n} catch (IllegalArgumentException e) {\n    log.warn(\"counter id beyond driver counter space\", e);\n}","preventionTips":["Allocate counters via the API so ids are always valid for this driver","Never reuse ids across drivers/sessions","Know your driver's MAX_COUNTERS configuration and assert against it"],"tags":["aeron","counters","bounds","illegal-argument"],"backgroundTag":"index-out-of-range","analyzedSha":"6d60124e15e35c11b49ba2e3c2c2858a09a18803","analyzedAt":"2026-09-12T11:17:07.683Z","contentChangedAt":"2026-09-12T11:17:07.683Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}