{"record":{"id":"ec85d5764f9e4851","repo":"apache/druid","slug":"cannot-add-element-of-size-d-greater-than-capaci","errorCode":null,"errorMessage":"cannot add element of size[%d] greater than capacity[%d]","messagePattern":"cannot add element of size\\[(.+?)\\] greater than capacity\\[(.+?)\\]","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"server/src/main/java/org/apache/druid/client/cache/BytesBoundedLinkedQueue.java","lineNumber":68,"sourceCode":"  private long capacity;\n\n  public BytesBoundedLinkedQueue(long capacity)\n  {\n    delegate = new ConcurrentLinkedQueue<>();\n    this.capacity = capacity;\n  }\n\n  private static void checkNotNull(Object v)\n  {\n    if (v == null) {\n      throw new NullPointerException();\n    }\n  }\n\n  private void checkSize(E e)\n  {\n    if (getBytesSize(e) > capacity) {\n      throw new IAE(\"cannot add element of size[%d] greater than capacity[%d]\", getBytesSize(e), capacity);\n    }\n  }\n\n  public abstract long getBytesSize(E e);\n\n  public void elementAdded(E e)\n  {\n    currentSize.addAndGet(getBytesSize(e));\n    elementCount.getAndIncrement();\n  }\n\n  public void elementRemoved(E e)\n  {\n    currentSize.addAndGet(-1 * getBytesSize(e));\n    elementCount.getAndDecrement();\n  }\n\n  private void fullyUnlock()","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/server/src/main/java/org/apache/druid/client/cache/BytesBoundedLinkedQueue.java#L50-L86","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Increase the configured capacity so it exceeds the largest single element","Reduce the size of elements being offered (split into smaller entries)","Skip caching oversized entries by checking size before offer","Fix unit mistakes in configuration (ensure capacity is in bytes)"],"exampleFix":"// before\nnew BytesBoundedLinkedQueue<>(1024); // element of 4096 bytes -> IAE\n// after\nnew BytesBoundedLinkedQueue<>(8 * 1024 * 1024); // capacity > max element size","handlingStrategy":"validation","validationCode":"long size = queue.getBytesSize(e);\nif (size > capacity) { /* skip caching or split entry */ return false; }\nqueue.offer(e);","typeGuard":null,"tryCatchPattern":"try { queue.offer(e); } catch (IllegalArgumentException e) { log.warn(\"entry too large for cache queue, skipping\"); }","preventionTips":["Configure capacity larger than the biggest cached element","Check element size before offering","Avoid unit mistakes (bytes vs MB) in cache config"],"tags":["cache","capacity","byte-size"],"backgroundTag":"value-out-of-range","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}