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 HashVectorGrouper: the configured max load factor for the open-addressing hash table must be strictly less than 1.0, otherwise the table can never terminate probing (no free bucket will ever be found). Any value >= 1.0f is rejected with this IAE at grouper construction.

Source

Thrown at processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/HashVectorGrouper.java:97

      final int keySize,
      final AggregatorAdapters aggregators,
      final int bufferGrouperMaxSize,
      final float maxLoadFactor,
      final int configuredInitialNumBuckets
  )
  {
    this.bufferSupplier = bufferSupplier;
    this.keySize = keySize;
    this.aggregators = aggregators;
    this.bufferGrouperMaxSize = bufferGrouperMaxSize;
    this.maxLoadFactor = maxLoadFactor > 0 ? maxLoadFactor : DEFAULT_MAX_LOAD_FACTOR;
    this.configuredInitialNumBuckets = configuredInitialNumBuckets >= MIN_BUCKETS
                                       ? configuredInitialNumBuckets
                                       : DEFAULT_INITIAL_BUCKETS;
    this.bucketSize = MemoryOpenHashTable.bucketSize(keySize, aggregators.spaceNeeded());

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

  @Override
  public void initVectorized(final int maxVectorSize)
  {
    if (!initialized) {
      this.buffer = bufferSupplier.get();
      this.maxNumBuckets = Math.max(
          computeRoundedInitialNumBuckets(buffer.capacity(), bucketSize, configuredInitialNumBuckets),
          computeMaxNumBucketsAfterGrowth(buffer.capacity(), bucketSize)
      );

      reset();

      this.vKeyHashCodes = new int[maxVectorSize];
      this.vAggregationPositions = new int[maxVectorSize];
      this.vAggregationRows = new int[maxVectorSize];

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Set maxLoadFactor to a value strictly below 1.0 (Druid's typical default is 0.5-0.9 range).
2. Clamp or validate the config before constructing the grouper, e.g. Math.min(0.99f, configuredValue).
3. If you need to hold more data, increase the max on-disk/buffer size rather than the load factor.

Example fix

// before
HashVectorGrouper grouper = new HashVectorGrouper(..., 1.0f, ...);
// after
float maxLoadFactor = Math.min(0.9f, configuredLoadFactor);
HashVectorGrouper grouper = new HashVectorGrouper(..., maxLoadFactor, ...);

if (!(maxLoadFactor > 0.0f && maxLoadFactor < 1.0f)) {
  throw new IllegalArgumentException("maxLoadFactor must be in (0,1): " + maxLoadFactor);
}

When it happens

Trigger: Constructing a HashVectorGrouper (directly or via groupBy v2 buffer / vectorized engine config) with a maxLoadFactor of 1.0 or greater, e.g. tuning GroupByStatsProvider/MaxIntermediateRows style knobs or programmatic grouper instantiation passing maxLoadFactor >= 1.0f.

Common situations: Hand-tuning performance knobs to squeeze more rows into the buffer; copying config values between engines where one uses a fraction and the other a percentage; misreading '1.0 = full' semantics.

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/e277fff45ee188b0. Report an issue: GitHub.