{"record":{"id":"ead27b5e788e0237","repo":"aeron-io/aeron","slug":"key-length-out-of-bounds-keylength","errorCode":null,"errorMessage":"key length out of bounds: <keyLength>","messagePattern":"key length out of bounds: <keyLength>","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/ClientConductor.java","lineNumber":1134,"sourceCode":"\n    Counter addCounter(\n        final int typeId,\n        final DirectBuffer keyBuffer,\n        final int keyOffset,\n        final int keyLength,\n        final DirectBuffer labelBuffer,\n        final int labelOffset,\n        final int labelLength)\n    {\n        clientLock.lock();\n        try\n        {\n            ensureActive();\n            ensureNotReentrant();\n\n            if (keyLength < 0 || keyLength > CountersManager.MAX_KEY_LENGTH)\n            {\n                throw new IllegalArgumentException(\"key length out of bounds: \" + keyLength);\n            }\n\n            if (labelLength < 0 || labelLength > CountersManager.MAX_LABEL_LENGTH)\n            {\n                throw new IllegalArgumentException(\"label length out of bounds: \" + labelLength);\n            }\n\n            final long registrationId = driverProxy.addCounter(\n                typeId, keyBuffer, keyOffset, keyLength, labelBuffer, labelOffset, labelLength);\n\n            awaitResponse(registrationId);\n\n            return (Counter)resourceByRegIdMap.get(registrationId);\n        }\n        finally\n        {\n            clientLock.unlock();\n        }","sourceCodeStart":1116,"sourceCodeEnd":1152,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/ClientConductor.java#L1116-L1152","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Shrink the key payload so keyLength <= CountersManager.MAX_KEY_LENGTH.","Fix keyOffset/keyLength computation and validate 0 <= keyLength before calling.","Store large metadata externally and keep only a small id/handle in the key."],"exampleFix":"// before\nint keyLength = serialized.length; // may exceed CountersManager.MAX_KEY_LENGTH\nclient.addCounter(typeId, keyBuffer, 0, keyLength, labelBuffer, 0, labelLength);\n// after\nint keyLength = Math.min(serialized.length, CountersManager.MAX_KEY_LENGTH); // or validate and fail with your own message\nif (serialized.length > CountersManager.MAX_KEY_LENGTH) throw new IllegalStateException(\"counter key too large\");","handlingStrategy":"validation","validationCode":"if (keyLength < 0 || keyLength > CountersManager.MAX_KEY_LENGTH) throw new IllegalArgumentException(\"keyLength=\" + keyLength);\nclient.addCounter(typeId, keyBuffer, keyOffset, keyLength, labelBuffer, labelOffset, labelLength);","typeGuard":null,"tryCatchPattern":"try { client.addCounter(typeId, keyBuffer, keyOffset, keyLength, labelBuffer, labelOffset, labelLength); } catch (IllegalArgumentException e) { log.error(\"counter key invalid: {}\", e.getMessage()); }","preventionTips":["Check CountersManager.MAX_KEY_LENGTH before encoding key metadata.","Store large metadata outside the counter key.","Assert keyOffset + keyLength fits within the key buffer."],"tags":["java","aeron","counters","bounds"],"backgroundTag":"value-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"}