apache/druid · error · IllegalArgumentException

Invalid maxLoadFactor[%f], must be < 1.0

Error message

Invalid maxLoadFactor[%f], must be < 1.0

What it means

Constructor validation in LimitedBufferHashGrouper: same invariant as HashVectorGrouper — maxLoadFactor must be strictly less than 1.0 because the heap-backed limited hash table needs free buckets to function. Values >= 1.0f throw this IAE; non-positive values are silently replaced with DEFAULT_MAX_LOAD_FACTOR, so only values in [1.0, inf) fail.

Source

Thrown at processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/LimitedBufferHashGrouper.java:85

  public LimitedBufferHashGrouper(
      final Supplier<ByteBuffer> bufferSupplier,
      final Grouper.KeySerde<KeyType> keySerde,
      final AggregatorAdapters aggregators,
      final int bufferGrouperMaxSize,
      final float maxLoadFactor,
      final int initialBuckets,
      final int limit,
      final boolean sortHasNonGroupingFields
  )
  {
    super(bufferSupplier, keySerde, aggregators, HASH_SIZE + keySerde.keySize(), bufferGrouperMaxSize);
    this.maxLoadFactor = maxLoadFactor > 0 ? maxLoadFactor : DEFAULT_MAX_LOAD_FACTOR;
    this.initialBuckets = initialBuckets > 0 ? Math.max(MIN_INITIAL_BUCKETS, initialBuckets) : DEFAULT_INITIAL_BUCKETS;
    this.limit = limit;
    this.sortHasNonGroupingFields = sortHasNonGroupingFields;

    if (this.maxLoadFactor >= 1.0f) {
      throw new IAE("Invalid maxLoadFactor[%f], must be < 1.0", maxLoadFactor);
    }

    // For each bucket, store an extra field indicating the bucket's current index within the heap when
    // pushing down limits (size Integer.BYTES).
    this.bucketSize = HASH_SIZE + keySerde.keySize() + Integer.BYTES + aggregators.spaceNeeded();
  }

  @Override
  public void init()
  {
    if (initialized) {
      return;
    }
    this.totalBuffer = bufferSupplier.get();

    // We check this already in SpillingGrouper to ensure that LimitedBufferHashGrouper is only used when there is
    // sufficient buffer capacity. If this error occurs, something went very wrong.
    if (!validateBufferCapacity(totalBuffer.capacity())) {

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Lower maxLoadFactor below 1.0 (0.5-0.9 is typical).
2. Fix units if the value came from a percent config (e.g. 95% -> 0.95, not 95 or 100).
3. Add an upstream config validator that rejects/clamps values >= 1.0 before engine startup.

Example fix

// before
class: "...", maxLoadFactor: 1.0
// after
maxLoadFactor: 0.8

if (!(maxLoadFactor > 0.0f && maxLoadFactor < 1.0f)) {
  maxLoadFactor = 0.8f; // or reject
}

When it happens

Trigger: Creating a LimitedBufferHashGrouper with maxLoadFactor >= 1.0f, typically via groupBy limit push-down configuration or programmatic construction for spilling/limit-limited group-bys.

Common situations: Tuning groupBy query server config (druid.query.groupBy.maxOnDiskStorage / load factor related knobs); misconfiguring fractional values as percentages (100 instead of 1.0-scale).

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Invalid maxLoadFactor[%f], must be < 1.0
• Failed to parse metric dimensions and types
• Cannot simultaneously replace and append to existing segment
• Interval[%s] is empty, must specify a nonempty interval
• Conflicting segment granularities found %s(segmentGranularit

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