{"record":{"id":"e277fff45ee188b0","repo":"apache/druid","slug":"invalid-maxloadfactor-f-must-be-1-0-e277ff","errorCode":null,"errorMessage":"Invalid maxLoadFactor[%f], must be < 1.0","messagePattern":"Invalid maxLoadFactor\\[(.+?)\\], must be < 1\\.0","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/HashVectorGrouper.java","lineNumber":97,"sourceCode":"      final int keySize,\n      final AggregatorAdapters aggregators,\n      final int bufferGrouperMaxSize,\n      final float maxLoadFactor,\n      final int configuredInitialNumBuckets\n  )\n  {\n    this.bufferSupplier = bufferSupplier;\n    this.keySize = keySize;\n    this.aggregators = aggregators;\n    this.bufferGrouperMaxSize = bufferGrouperMaxSize;\n    this.maxLoadFactor = maxLoadFactor > 0 ? maxLoadFactor : DEFAULT_MAX_LOAD_FACTOR;\n    this.configuredInitialNumBuckets = configuredInitialNumBuckets >= MIN_BUCKETS\n                                       ? configuredInitialNumBuckets\n                                       : DEFAULT_INITIAL_BUCKETS;\n    this.bucketSize = MemoryOpenHashTable.bucketSize(keySize, aggregators.spaceNeeded());\n\n    if (this.maxLoadFactor >= 1.0f) {\n      throw new IAE(\"Invalid maxLoadFactor[%f], must be < 1.0\", maxLoadFactor);\n    }\n  }\n\n  @Override\n  public void initVectorized(final int maxVectorSize)\n  {\n    if (!initialized) {\n      this.buffer = bufferSupplier.get();\n      this.maxNumBuckets = Math.max(\n          computeRoundedInitialNumBuckets(buffer.capacity(), bucketSize, configuredInitialNumBuckets),\n          computeMaxNumBucketsAfterGrowth(buffer.capacity(), bucketSize)\n      );\n\n      reset();\n\n      this.vKeyHashCodes = new int[maxVectorSize];\n      this.vAggregationPositions = new int[maxVectorSize];\n      this.vAggregationRows = new int[maxVectorSize];","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/HashVectorGrouper.java#L79-L115","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set maxLoadFactor to a value strictly below 1.0 (Druid's typical default is 0.5-0.9 range).","Clamp or validate the config before constructing the grouper, e.g. Math.min(0.99f, configuredValue).","If you need to hold more data, increase the max on-disk/buffer size rather than the load factor."],"exampleFix":"// before\nHashVectorGrouper grouper = new HashVectorGrouper(..., 1.0f, ...);\n// after\nfloat maxLoadFactor = Math.min(0.9f, configuredLoadFactor);\nHashVectorGrouper grouper = new HashVectorGrouper(..., maxLoadFactor, ...);","handlingStrategy":"validation","validationCode":"if (!(maxLoadFactor > 0.0f && maxLoadFactor < 1.0f)) {\n  throw new IllegalArgumentException(\"maxLoadFactor must be in (0,1): \" + maxLoadFactor);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep load factors in the 0.5-0.9 range","Never convert percentage configs (95) directly to the float field — divide by 100","Add startup config validation for grouper tuning knobs"],"tags":["druid","group-by","hash-table","config"],"backgroundTag":"invalid-config-value","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}