aeron-io/aeron · error · IllegalArgumentException

EINVAL

EINVAL

Error message

initialCapacity outside range 0 - ${max}${capacity}

What it means

BufferBuilder validates that its initial allocation does not exceed BUFFER_BUILDER_MAX_CAPACITY. Passing an initialCapacity above that compile-time maximum would allocate a buffer the builder can never grow within, so the constructor throws IllegalArgumentException with EINVAL.

Solutions

1. Pass an initialCapacity <= BUFFER_BUILDER_MAX_CAPACITY, or use the default 0
2. Check the requested capacity against BUFFER_BUILDER_MAX_CAPACITY before constructing
3. Clamp or scale down large capacity requests at configuration load time

Example fix

// before
concurrent::atomic::BufferBuilder builder(3u * 1024 * 1024 * 1024u); // exceeds max
// after
constexpr std::uint32_t cap = std::min(requested, BUFFER_BUILDER_MAX_CAPACITY);
concurrent::atomic::BufferBuilder builder(cap);

if (initialCapacity > BUFFER_BUILDER_MAX_CAPACITY) {
    initialCapacity = BUFFER_BUILDER_MAX_CAPACITY; // or reject the config
}

try {
    concurrent::atomic::BufferBuilder builder(initialCapacity);
} catch (const aeron::util::IllegalArgumentException& e) {
    // clamp and retry
}

When it happens

Trigger: Constructing BufferBuilder with an explicit initialCapacity greater than BUFFER_BUILDER_MAX_CAPACITY (e.g. BufferBuilder builder(2u << 30)).

Common situations: Tuning initial capacity for large fragments and overshooting the maximum; porting code that assumed a 64-bit capacity constant; copying a capacity value from a differently-configured build.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• insufficient capacity: maxCapacity=
• initialCapacity outside range 0
• limit outside range: capacity=
• unknown RES_TYPE=
• Insufficient length:

AI-assisted analysis of aeron-io/aeron@6d60124e15 (2026-09-12). Data as JSON: /api/errors/993f809f636004af. Report an issue: GitHub.

Appendix: source

Thrown at aeron-client/src/main/cpp_wrapper/BufferBuilder.h:39

#include "Aeron.h"

namespace aeron
{

static constexpr std::uint32_t BUFFER_BUILDER_MAX_CAPACITY = std::numeric_limits<std::int32_t>::max() - 8;
static constexpr std::uint32_t BUFFER_BUILDER_INIT_MIN_CAPACITY = 4096;

class BufferBuilder
{
public:
    using this_t = BufferBuilder;

    explicit BufferBuilder(std::uint32_t initialCapacity = 0) :
        m_capacity(initialCapacity),
        m_buffer(new std::uint8_t[m_capacity])
    {
        if (BUFFER_BUILDER_MAX_CAPACITY < m_capacity)
        {
            throw IllegalArgumentException(
                "initialCapacity outside range 0 - " + std::to_string(BUFFER_BUILDER_MAX_CAPACITY) +
                ": capacity=" + std::to_string(m_capacity), SOURCEINFO, EINVAL);
        }
    }

    BufferBuilder(BufferBuilder &&builder) noexcept:
        m_capacity(builder.m_capacity),
        m_limit(builder.m_limit),
        m_nextTermOffset(builder.m_nextTermOffset),
        m_buffer(std::move(builder.m_buffer))
    {
    }

    std::uint8_t *buffer() const
    {
        return &m_buffer[0];
    }

View on GitHub (pinned to 6d60124e15)