{"record":{"id":"61bf2e06969da177","repo":"aeron-io/aeron","slug":"offset-capacity","errorCode":null,"errorMessage":"offset= capacity=","messagePattern":"offset= capacity=","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/DirectBufferVector.java","lineNumber":148,"sourceCode":"    {\n        this.length = length;\n        return this;\n    }\n\n    /**\n     * Ensure the vector is valid for the buffer.\n     *\n     * @throws NullPointerException if the buffer is null.\n     * @throws IllegalArgumentException if the offset is out of range for the buffer.\n     * @throws IllegalArgumentException if the length is out of range for the buffer.\n     * @return this for a fluent API.\n     */\n    public DirectBufferVector validate()\n    {\n        final int capacity = buffer.capacity();\n        if (offset < 0 || offset >= capacity)\n        {\n            throw new IllegalArgumentException(\"offset=\" + offset + \" capacity=\" + capacity);\n        }\n\n        if (length < 0 || length > (capacity - offset))\n        {\n            throw new IllegalArgumentException(\"offset=\" + offset + \" capacity=\" + capacity + \" length=\" + length);\n        }\n\n        return this;\n    }\n\n    /**\n     * {@inheritDoc}\n     */\n    @Override\n    public String toString()\n    {\n        return \"DirectBufferVector{\" +\n            \"buffer=\" + buffer +","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/DirectBufferVector.java#L130-L166","documentation":"DirectBufferVector.validate() throws IllegalArgumentException when the vector's offset is negative or points past the end of the underlying buffer's capacity. Aeron validates each vector before it is used in a vectored write (e.g. publish(vectors...)) so that no memory region outside the buffer is ever read. The exception carries the offending offset and the buffer capacity for diagnosis.","triggerScenarios":"Calling Publication.tryClaim or a vectored offer/publish API with a DirectBufferVector whose offset is < 0 or >= buffer.capacity(). Typically caused by computing the offset from a stale buffer (buffer re-wrapped or swapped after the vector was built) or a wrong arithmetic offset value.","commonSituations":"Passing -1 as a sentinel offset; reusing a vector created for a different (larger) buffer; wrapping a buffer with offset arithmetic (wrap(buffer, baseOffset)) then compounding another offset on top; buffer resized/reallocated between vector construction and send.","solutions":["Check the offset computation: ensure 0 <= offset and offset < buffer.capacity() before constructing the vector.","If the vector is reused, re-wrap or rebuild it each time the underlying buffer changes so offset/capacity stay consistent.","Log offset and buffer.capacity() at construction time to find where the negative/too-large offset originates."],"exampleFix":"// before\nDirectBufferVector vector = new DirectBufferVector(headerBuffer, headerOffset, length);\n// after\nint off = headerOffset & 0x7FFFFFFF; // or fix the arithmetic\nif (off >= headerBuffer.capacity()) { off = 0; }\nDirectBufferVector vector = new DirectBufferVector(headerBuffer, off, length);","handlingStrategy":"validation","validationCode":"if (vector.buffer() == null || vector.offset() < 0 || vector.offset() >= vector.buffer().capacity()) {\n    throw new IllegalArgumentException(\"vector offset \" + vector.offset() + \" invalid for capacity \" + vector.buffer().capacity());\n}","typeGuard":"boolean isValidVector(DirectBufferVector v) {\n    return v != null && v.buffer() != null && v.offset() >= 0 && v.offset() < v.buffer().capacity();\n}","tryCatchPattern":"try {\n    publication.offer(vectorBuffer, vectorOffset, vectorLength);\n} catch (IllegalArgumentException e) {\n    log.error(\"invalid vector offset/capacity\", e);\n    metrics.vectorValidationFailures.increment();\n}","preventionTips":["Always derive vector offsets from the same buffer instance the vector wraps.","Assert offset bounds immediately after computing them, before constructing the vector.","Avoid sentinel negative offsets; use explicit constants and check them before the call."],"tags":["aeron","buffer-vector","argument-validation","offset-out-of-range"],"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"}