MyCATApache/Mycat-Server · error · IllegalArgumentException

bufferSize must not be less than 1

Error message

bufferSize must not be less than 1

What it means

RingBuffer's constructor validates the sequencer's buffer size: it must be at least 1 (and, in the next check, a power of 2, so indices wrap with bitmask arithmetic m & (2^n - 1)). A bufferSize < 1 cannot be indexed or wrapped, so the constructor throws IllegalArgumentException.

Solutions

1. Pass a bufferSize >= 1 (conventionally a power of 2 like 1024) when creating the sequencer/ring buffer.
2. Fix the config property supplying bufferSize so it parses to a valid positive integer: `Math.max(1, configuredSize)`.
3. If bufferSize is computed, guard the calculation: fall back to a default (e.g. 1024) when the result is < 1.
4. Validate early at config-load time that bufferSize >= 1 and Integer.bitCount(bufferSize) == 1.

Example fix

// before
int bufferSize = Integer.getInteger("mycat.ring.buffer.size", 0);
RingBuffer<Event> rb = new RingBuffer<>(factory, create(factory, bufferSize));
// after
int bufferSize = Math.max(1024,
    Integer.getInteger("mycat.ring.buffer.size", 1024));
RingBuffer<Event> rb = new RingBuffer<>(factory, create(factory, bufferSize));

int bufferSize = sequencer.getBufferSize();
if (bufferSize < 1 || Integer.bitCount(bufferSize) != 1) {
  bufferSize = 1024; // safe default power of 2
  sequencer = new MultiProducerSequencer(bufferSize, waitStrategy);
}
RingBuffer<E> rb = new RingBuffer<>(eventFactory, sequencer);

try {
  rb = new RingBuffer<>(eventFactory, sequencer);
} catch (IllegalArgumentException e) {
  sequencer = new MultiProducerSequencer(1024, waitStrategy);
  rb = new RingBuffer<>(eventFactory, sequencer);
}

When it happens

Trigger: Constructing `new RingBuffer(eventFactory, sequencer)` where sequencer.getBufferSize() returns 0 or a negative value — typically via `RingBuffer.createMultiProducer(create(eventFactory, bufferSize), ...)`-style helpers with a bad bufferSize argument.

Common situations: Reading bufferSize from config that defaulted to 0 (unset property, failed parse); computing bufferSize as `(long) size/threads` with size < threads; passing an uncomputed/zero placeholder.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• bufferSize must be a power of 2
• Initial capacity exceeds maximum capacity of
• Page size cannot exceed
• Both batchStartsAt and batchSize must be positive but got…
• Initial capacity must be greater than 0

AI-assisted analysis of MyCATApache/Mycat-Server@65f8d8beb7 (2026-09-11). Data as JSON: /api/errors/c35d19eb04d662ee. Report an issue: GitHub.

Appendix: source

Thrown at src/main/java/io/mycat/memory/unsafe/ringbuffer/RingBuffer.java:47

        } else {
            throw new IllegalStateException("Unknown pointer size");
        }
        //需要填充128字节，缓存行长度一般是128字节
        BUFFER_PAD = 128 / scale;
        REF_ARRAY_BASE = Platform.arrayBaseOffset(Object[].class) + (BUFFER_PAD << REF_ELEMENT_SHIFT);
    }

    private final long indexMask;
    private final Object[] entries;
    protected final int bufferSize;
    protected final Sequencer sequencer;

    public RingBuffer(EventFactory<E> eventFactory, Sequencer sequencer) {
        this.sequencer = sequencer;
        this.bufferSize = sequencer.getBufferSize();
        //保证buffer大小不小于1
        if (bufferSize < 1) {
            throw new IllegalArgumentException("bufferSize must not be less than 1");
        }
        //保证buffer大小为2的n次方
        if (Integer.bitCount(bufferSize) != 1) {
            throw new IllegalArgumentException("bufferSize must be a power of 2");
        }
        //m % 2^n  <=>  m & (2^n - 1)
        this.indexMask = bufferSize - 1;
        /**
         * 结构：缓存行填充，避免频繁访问的任一entry与另一被修改的无关变量写入同一缓存行
         * --------------
         * *   数组头   * BASE
         * *   Padding  * 128字节
         * * reference1 * SCALE
         * * reference2 * SCALE
         * * reference3 * SCALE
         * ..........
         * *   Padding  * 128字节
         * --------------

View on GitHub (pinned to 65f8d8beb7)