LMAX-Exchange/disruptor · error · IllegalArgumentException

bufferSize must be a power of 2

Error message

bufferSize must be a power of 2

What it means

Defensive check in RingBufferFields: the capacity from the sequencer is less than 1. Redundant with AbstractSequencer's own check for standard sequencers; it protects RingBuffer against custom Sequencer implementations returning 0 or negative sizes, which would make the backing entry array unusable.

Source

Thrown at src/main/java/com/lmax/disruptor/RingBuffer.java:56

    private final E[] entries;
    protected final int bufferSize;
    protected final Sequencer sequencer;

    @SuppressWarnings("unchecked")
    RingBufferFields(
        final EventFactory<E> eventFactory,
        final Sequencer sequencer)
    {
        this.sequencer = sequencer;
        this.bufferSize = sequencer.getBufferSize();

        if (bufferSize < 1)
        {
            throw new IllegalArgumentException("bufferSize must not be less than 1");
        }
        if (Integer.bitCount(bufferSize) != 1)
        {
            throw new IllegalArgumentException("bufferSize must be a power of 2");
        }

        this.indexMask = bufferSize - 1;
        this.entries = (E[]) new Object[bufferSize + 2 * BUFFER_PAD];
        fill(eventFactory);
    }

    private void fill(final EventFactory<E> eventFactory)
    {
        for (int i = 0; i < bufferSize; i++)
        {
            entries[BUFFER_PAD + i] = eventFactory.newInstance();
        }
    }

    protected final E elementAt(final long sequence)
    {
        return entries[BUFFER_PAD + (int) (sequence & indexMask)];

View on GitHub (pinned to c871ca4982)

Solutions

1. Ensure the supplied Sequencer reports a positive power-of-2 capacity.
2. Extend AbstractSequencer instead of implementing Sequencer directly.
3. Stub getBufferSize() in tests with a valid size.

Example fix

// before
when(mockSequencer.getBufferSize()).thenReturn(0); // or left unstubbed

// after
when(mockSequencer.getBufferSize()).thenReturn(1024);

if (sequencer.getBufferSize() < 1) throw new IllegalArgumentException("invalid sequencer bufferSize");

When it happens

Trigger: Constructing a RingBuffer over a custom or mocked Sequencer whose getBufferSize() returns 0/negative; delegating constructors in RingBuffer subclasses that pass an uninitialised size.

Common situations: Mockito default return of 0 for unstubbed getBufferSize(); custom sequencer wrapper that drops the bufferSize field.

Related errors

• Thread is already running
• bufferSize must not be less than 1
• bufferSize must not be less than 1
• bufferSize must be a power of 2
• n must be > 0 and < bufferSize

AI-assisted analysis of LMAX-Exchange/disruptor@c871ca4982 (2026-08-14). Data as JSON: /api/errors/729cd6bc0086a096. Report an issue: GitHub.