What causes "The inner list is full!" in microsoft/FASTER?

Increase DefaultCapacity (it is a power-of-two mask, so use 2^n sizing) to accommodate peak in-flight items.

microsoft/FASTER · error · InvalidOperationException

The inner list is full!

Error message

The inner list is full!

What it means

The single ElasticCircularBuffer (fixed DefaultCapacity-sized ring) Enqueue found the ring full: advancing tail would collide with head. The buffer is a fixed-size power-of-two ring, so callers must ensure capacity before enqueueing or use the elastic (multi-buffer) variant; otherwise the enqueue is rejected with InvalidOperationException.

Solutions

Increase DefaultCapacity (it is a power-of-two mask, so use 2^n sizing) to accommodate peak in-flight items.
Check IsFull before Enqueue and block/drop/backpressure the producer accordingly.
Ensure the consumer is running and not stuck; drain faster than production in steady state.
Use the elastic (multi-buffer) constructor so new segments are allocated on overflow instead of throwing.

Example fix

// before
queue.Enqueue(ref item);

// after
if (queue.IsFull())
{
    // apply backpressure or grow capacity
}
else
{
    queue.Enqueue(ref item);
}

Defensive patterns

Strategy: validation

Validate before calling

// check capacity before producing
if (queue.IsFull())
{
    // apply backpressure, drop, or grow capacity
}
else
{
    queue.Enqueue(ref item);
}

Try / catch

try { queue.Enqueue(ref item); }
catch (InvalidOperationException ex) when (ex.Message.Contains("full"))
{
    // backpressure: wait for the consumer to drain, then retry
    await consumerDrainedTask; queue.Enqueue(ref item);
}

Prevention

Size the ring as a power of two with headroom for peak bursts.
Check IsFull before every enqueue in producer loops.
Monitor consumer lag and alert before capacity is exhausted.
Prefer the elastic constructor when the producer rate is unbounded.

When it happens

Trigger: Calling Enqueue on a single-buffer ElasticCircularBuffer already containing DefaultCapacity items — producers outpacing consumers with no capacity check.

Common situations: Burst traffic where the consumer (e.g., network writer) stalls; sizing DefaultCapacity too small for in-flight messages; forgetting to check IsFull before enqueue in a tight producer loop.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of microsoft/FASTER@321d872eab (2026-09-15). Data as JSON: /api/errors/80f9aa5943b7718b. Report an issue: GitHub.

Appendix: source

Thrown at cs/remote/src/FASTER.common/ElasticCircularBuffer.cs:48

        }

        public T PeekFirst()
        {
            return Items[head];
        }

        public T PeekLast()
        {
            return Items[(tail - 1) & DefaultCapacity];
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public void Enqueue(ref T value)
        {
            int next = (tail + 1) & DefaultCapacity;
            if (next == head)
            {
                throw new InvalidOperationException("The inner list is full!");
            }
            Items[tail] = value;
            tail = next;
        }

        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public T Dequeue()
        {
            if (head == tail)
            {
                throw new InvalidOperationException("The list is empty!");
            }
            int oldhead = head;
            head = (head + 1) & DefaultCapacity;
            var ret = Items[oldhead];
            Items[oldhead] = default;
            return ret;
        }

View on GitHub (pinned to 321d872eab)