apache/hadoop · error · IllegalArgumentException

Illegal maxload factor: {}

Error message

Illegal maxload factor: {}

What it means

LightWeightHashSet (and its subclass LightWeightLinkedSet) validates constructor arguments: maxLoadFactor must satisfy 0 < maxLoadFactor <= 1.0 because it is multiplied by bucket capacity to compute the expand threshold. Anything outside that range is rejected immediately with IllegalArgumentException - a fail-fast programming error, not a runtime environment condition.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/util/LightWeightHashSet.java:113

  private final int expandMultiplier = 2;

  private int expandThreshold;
  private int shrinkThreshold;

  /**
   * @param initCapacity
   *          Recommended size of the internal array.
   * @param maxLoadFactor
   *          used to determine when to expand the internal array
   * @param minLoadFactor
   *          used to determine when to shrink the internal array
   */
  @SuppressWarnings("unchecked")
  public LightWeightHashSet(int initCapacity, float maxLoadFactor,
      float minLoadFactor) {

    if (maxLoadFactor <= 0 || maxLoadFactor > 1.0f)
      throw new IllegalArgumentException("Illegal maxload factor: "
          + maxLoadFactor);

    if (minLoadFactor <= 0 || minLoadFactor > maxLoadFactor)
      throw new IllegalArgumentException("Illegal minload factor: "
          + minLoadFactor);

    this.initialCapacity = computeCapacity(initCapacity);
    this.capacity = this.initialCapacity;
    this.hash_mask = capacity - 1;

    this.maxLoadFactor = maxLoadFactor;
    this.expandThreshold = (int) (capacity * maxLoadFactor);
    this.minLoadFactor = minLoadFactor;
    this.shrinkThreshold = (int) (capacity * minLoadFactor);

    entries = new LinkedElement[capacity];
    if (LOG.isDebugEnabled()) {
      LOG.debug("initial capacity=" + initialCapacity + ", max load factor= "

View on GitHub (pinned to 2add963021)

Solutions

1. Pass maxLoadFactor as a fraction in (0, 1.0]; use the library defaults DEFAULT_MAX_LOAD_FACTOR = 0.75f when unsure.
2. If the value arrives as a percentage from config, divide by 100 and range-check before constructing.
3. Add a constructor-argument unit test with boundary values (0, 1.0, just above 1.0) in the wrapper that builds the set.

Example fix

// before
float pct = conf.getFloat("my.hash.load.percent", 75); // percent semantics
new LightWeightLinkedSet<>(16, pct, 20); // 75 > 1.0f -> IllegalArgumentException

// after
float max = conf.getFloat("my.hash.load.percent", 75) / 100f;
float min = conf.getFloat("my.hash.min.load.percent", 20) / 100f;
if (max <= 0f || max > 1f || min <= 0f || min > max) {
  throw new IllegalArgumentException("load factors out of range: max=" + max + ", min=" + min);
}
new LightWeightLinkedSet<>(16, max, min);

static boolean isValidMaxLoadFactor(float f) {
  return f > 0f && f <= 1.0f;
}
// before constructing:
if (!isValidMaxLoadFactor(max)) throw new IllegalArgumentException("max load factor must be in (0,1]: " + max);

static boolean isValidMaxLoadFactor(float f) { return f > 0f && f <= 1.0f; }

When it happens

Trigger: Invoking the 3-arg constructor new LightWeightHashSet<>(initCapacity, maxLoadFactor, minLoadFactor) (or LightWeightLinkedSet with the same args) with maxLoadFactor <= 0 (0f, negative) or > 1.0f (1.5f, 75f). Common source: passing a percentage where a fraction is expected.

Common situations: Porting tuning values from another hash table that expresses load factor as a percent (75 instead of 0.75f); a config lookup returning a -1 'unset' sentinel that flows into the constructor; unit tests probing boundaries.

Related errors

• Illegal minload factor: {}
• Path must be absolute: " + path
• Copy destination must be different from source for %s.
• Block size must be greater than 0
• Replication must be greater than 0

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/7f2949141a74651b. Report an issue: GitHub.