{"record":{"id":"046acb1424cd1e4b","repo":"aeron-io/aeron","slug":"initialcapacity-outside-range-0-max-capacity-initialcapacity","errorCode":null,"errorMessage":"initialCapacity outside range 0 - <MAX_CAPACITY>: initialCapacity=<initialCapacity>","messagePattern":"initialCapacity outside range 0 - <MAX_CAPACITY>: initialCapacity=<initialCapacity>","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/BufferBuilder.java","lineNumber":82,"sourceCode":"     *\n     * @param initialCapacity at which the capacity will start.\n     */\n    public BufferBuilder(final int initialCapacity)\n    {\n        this(initialCapacity, false);\n    }\n\n    /**\n     * Construct a buffer builder with an initial capacity.\n     *\n     * @param initialCapacity at which the capacity will start.\n     * @param isDirect        is the underlying buffer to be a direct {@link ByteBuffer}\n     */\n    public BufferBuilder(final int initialCapacity, final boolean isDirect)\n    {\n        if (initialCapacity < 0 || initialCapacity > MAX_CAPACITY)\n        {\n            throw new IllegalArgumentException(\"initialCapacity outside range 0 - \" + MAX_CAPACITY +\n                \": initialCapacity=\" + initialCapacity);\n        }\n\n        this.isDirect = isDirect;\n        if (isDirect)\n        {\n            if (initialCapacity > 0)\n            {\n                buffer.wrap(newDirectBuffer(initialCapacity));\n            }\n            headerBuffer.wrap(newDirectBuffer(HEADER_LENGTH));\n        }\n        else\n        {\n            if (initialCapacity > 0)\n            {\n                buffer.wrap(new byte[initialCapacity]);\n            }","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/BufferBuilder.java#L64-L100","documentation":"BufferBuilder's constructor validates initialCapacity against [0, MAX_CAPACITY] and throws IllegalArgumentException when it is negative or exceeds the maximum. BufferBuilder backs its data with a single bounded buffer, so an oversized initial capacity cannot be honored.","triggerScenarios":"new BufferBuilder(negativeValue, ...) or initialCapacity greater than MAX_CAPACITY (Integer.MAX_VALUE-derived cap) — typically from a bad constant, misconfigured setting, or overflowed computation.","commonSituations":"Passing a config value read from properties/env without clamping; computing initial capacity from a length/2x-doubling arithmetic that overflowed; copying a capacity from another, larger buffer.","solutions":["Clamp initialCapacity to [0, MAX_CAPACITY] before constructing: Math.max(0, Math.min(value, BufferBuilder.MAX_CAPACITY)).","Fix the source of the bad value (config parsing, overflow-prone arithmetic).","Rely on the default constructor or BufferBuilder's auto-resizing instead of a huge initial capacity — it grows as needed."],"exampleFix":"// before\nBufferBuilder b = new BufferBuilder(cfg, true);\n// after\nint capped = Math.max(0, Math.min(cfg, BufferBuilder.MAX_CAPACITY));\nBufferBuilder b = new BufferBuilder(capped, true);","handlingStrategy":"validation","validationCode":"int capped = Math.max(0, Math.min(initialCapacity, BufferBuilder.MAX_CAPACITY));\nBufferBuilder b = new BufferBuilder(capped, isDirect);","typeGuard":null,"tryCatchPattern":"try {\n    builder = new BufferBuilder(initialCapacity, true);\n} catch (IllegalArgumentException e) {\n    builder = new BufferBuilder(); // fall back to defaults\n}","preventionTips":["Clamp config-derived capacities before constructing","Watch for overflow in computed capacities (2x growth loops)","Prefer defaults/auto-resizing unless profiling shows a need"],"tags":["aeron","buffer","illegal-argument","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"}