{"record":{"id":"7e5227fca6f75206","repo":"aeron-io/aeron","slug":"insufficient-capacity-maxcapacity-max-capacity-limit-limit","errorCode":null,"errorMessage":"insufficient capacity: maxCapacity=<MAX_CAPACITY> limit=<limit> additionalLength=<additionalLength>","messagePattern":"insufficient capacity: maxCapacity=<MAX_CAPACITY> limit=<limit> additionalLength=<additionalLength>","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"aeron-client/src/main/java/io/aeron/BufferBuilder.java","lineNumber":271,"sourceCode":"            .fragmentedFrameLength(fragmentedFrameLength);\n\n        headerBuffer.putInt(FRAME_LENGTH_FIELD_OFFSET, HEADER_LENGTH + limit, LITTLE_ENDIAN);\n        // compute complete flags\n        headerBuffer.putByte(FLAGS_OFFSET, (byte)(headerBuffer.getByte(FLAGS_OFFSET) | header.flags()));\n\n        return completeHeader;\n    }\n\n    private void ensureCapacity(final int additionalLength)\n    {\n        final long requiredCapacity = (long)limit + additionalLength;\n        final int capacity = buffer.capacity();\n\n        if (requiredCapacity > capacity)\n        {\n            if (requiredCapacity > MAX_CAPACITY)\n            {\n                throw new IllegalStateException(\n                    \"insufficient capacity: maxCapacity=\" + MAX_CAPACITY +\n                    \" limit=\" + limit +\n                    \" additionalLength=\" + additionalLength);\n            }\n\n            resize(findSuitableCapacity(capacity, requiredCapacity));\n        }\n    }\n\n    private void resize(final int newCapacity)\n    {\n        if (isDirect)\n        {\n            final ByteBuffer byteBuffer = newDirectBuffer(newCapacity);\n            buffer.getBytes(0, byteBuffer, 0, limit);\n            buffer.wrap(byteBuffer);\n        }\n        else","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/aeron-io/aeron/blob/6d60124e15e35c11b49ba2e3c2c2858a09a18803/aeron-client/src/main/java/io/aeron/BufferBuilder.java#L253-L289","documentation":"ensureCapacity throws IllegalStateException when the required capacity (existing data + additionalLength) exceeds MAX_CAPACITY — the builder cannot grow any further because it is capped by maximum int-addressable/allowed size. The message gives maxCapacity, current limit, and the additional bytes requested.","triggerScenarios":"Appending (append/ensureCapacity) a chunk that would push total required bytes beyond MAX_CAPACITY; typically after many appends without compaction or with a huge single message.","commonSituations":"Accumulating messages into a BufferBuilder without resetting between streams; receiving unexpectedly large frames (bad framing/protocol desync) inflating required length; forwarding an untrusted length field from a malformed message.","solutions":["Call reset() when the previous message is fully consumed so the builder reuses space instead of growing unbounded.","Validate frame/message lengths against an application-level max before appending.","Fix framing logic if a corrupted stream produces absurd length fields.","Split the data across multiple BufferBuilder instances or streams if genuinely larger than MAX_CAPACITY."],"exampleFix":"// before\nbuilder.append(buffer, offset, hugeLength); // may exceed MAX_CAPACITY\n// after\nif (builder.limit() + hugeLength <= BufferBuilder.MAX_CAPACITY) {\n    builder.append(buffer, offset, hugeLength);\n} else {\n    throw new ProtocolError(\"message too large: \" + hugeLength);\n}","handlingStrategy":"try-catch","validationCode":"if ((long) builder.limit() + additionalLength > BufferBuilder.MAX_CAPACITY) {\n    throw new MessageTooLargeException(\"appending \" + additionalLength + \" would exceed max capacity\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    builder.append(buffer, offset, length);\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"insufficient capacity\")) {\n        builder.reset(); // or reject the oversized message\n    } else throw e;\n}","preventionTips":["reset() the builder between messages/streams","Enforce an application-level max message size before append","Validate length fields from the wire — huge lengths often mean framing desync"],"tags":["aeron","buffer","capacity","out-of-memory"],"backgroundTag":"payload-too-large","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"}