apache/druid · error · IllegalArgumentException

cannot add element of size

Error message

cannot add element of size[%d] greater than capacity[%d]

What it means

BytesBoundedLinkedQueue bounds the total serialized byte size of its queued elements. checkSize() throws IAE when a single element's byte size alone exceeds the queue's configured capacity, because such an element could never fit regardless of queue occupancy.

Solutions

1. Increase the configured capacity so it exceeds the largest single element
2. Reduce the size of elements being offered (split into smaller entries)
3. Skip caching oversized entries by checking size before offer
4. Fix unit mistakes in configuration (ensure capacity is in bytes)

Example fix

// before
new BytesBoundedLinkedQueue<>(1024); // element of 4096 bytes -> IAE
// after
new BytesBoundedLinkedQueue<>(8 * 1024 * 1024); // capacity > max element size

long size = queue.getBytesSize(e);
if (size > capacity) { /* skip caching or split entry */ return false; }
queue.offer(e);

try { queue.offer(e); } catch (IllegalArgumentException e) { log.warn("entry too large for cache queue, skipping"); }

When it happens

Trigger: Calling offer(e) where getBytesSize(e) > capacity — e.g. an enormous cached value or batch larger than the configured byte limit (druid.cache.sizeInBytes for hybrid/L2 queues).

Common situations: Cache capacity configured smaller than the largest cached object; large segments/results fed into a small floodgate cache; misconfigured unit (bytes vs MB) making capacity tiny.

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

• Column capacity exceeded
• Column capacity exceeded
• Column capacity exceeded
• Column capacity exceeded
• Column capacity exceeded

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/ec85d5764f9e4851. Report an issue: GitHub.

Appendix: source

Thrown at server/src/main/java/org/apache/druid/client/cache/BytesBoundedLinkedQueue.java:68

  private long capacity;

  public BytesBoundedLinkedQueue(long capacity)
  {
    delegate = new ConcurrentLinkedQueue<>();
    this.capacity = capacity;
  }

  private static void checkNotNull(Object v)
  {
    if (v == null) {
      throw new NullPointerException();
    }
  }

  private void checkSize(E e)
  {
    if (getBytesSize(e) > capacity) {
      throw new IAE("cannot add element of size[%d] greater than capacity[%d]", getBytesSize(e), capacity);
    }
  }

  public abstract long getBytesSize(E e);

  public void elementAdded(E e)
  {
    currentSize.addAndGet(getBytesSize(e));
    elementCount.getAndIncrement();
  }

  public void elementRemoved(E e)
  {
    currentSize.addAndGet(-1 * getBytesSize(e));
    elementCount.getAndDecrement();
  }

  private void fullyUnlock()

View on GitHub (pinned to 9b90983fd2)