apache/hadoop · error · IllegalArgumentException

Illagal value: ${NAME} = ${value} < MIN = ${MIN}

Error message

Illagal value: ${NAME} = ${value} < MIN = ${MIN}

What it means

Companion upper-bound guard in LongBitFormat.combine(): after the value < MIN check (line 63), the throw at line 67 rejects value > MAX, where MAX = (2^LENGTH)-1 for the field's allotted bits — the value does not fit the field. The message uses the same 'Illagal value' template (the catalog's '< MIN' wording is swapped; the line-67 branch reports '> MAX'). This is a bit-field overflow while packing a 64-bit record.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/util/LongBitFormat.java:67

    LENGTH = length;
    MIN = min;
    MAX = ((-1L) >>> (64 - LENGTH));
    MASK = MAX << OFFSET;
  }

  /** Retrieve the value from the record. */
  public long retrieve(long record) {
    return (record & MASK) >>> OFFSET;
  }

  /** Combine the value to the record. */
  public long combine(long value, long record) {
    if (value < MIN) {
      throw new IllegalArgumentException(
          "Illagal value: " + NAME + " = " + value + " < MIN = " + MIN);
    }
    if (value > MAX) {
      throw new IllegalArgumentException(
          "Illagal value: " + NAME + " = " + value + " > MAX = " + MAX);
    }
    return (record & ~MASK) | (value << OFFSET);
  }

  public long getMin() {
    return MIN;
  }

  public int getLength() {
    return LENGTH;
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Before combine(), validate value against the field's MAX (BITS.retrieve(-1L) or compute 2^LENGTH-1) and fail with a descriptive message
2. Widen the field (increase LENGTH) or restructure the bit layout so the value fits
3. If hit inside stock NameNode code, verify all nodes run the same Hadoop version (header layouts differ across releases) and report with the field NAME from the message

Example fix

// before
long header = HeaderFormat.BLOCKSIZE.combine(1L << 48, header);

// after
long max = HeaderFormat.BLOCKSIZE.retrieve(-1L);
if (blocksize > max) {
  throw new IllegalArgumentException("blocksize " + blocksize + " exceeds field MAX " + max);
}
long header = HeaderFormat.BLOCKSIZE.combine(blocksize, header);

long max = field.retrieve(-1L); // all-ones record yields the field's MAX
if (value > max) {
  throw new IllegalArgumentException(field.getName() + " needs " + (64 - Long.numberOfLeadingZeros(value))
      + " bits but field has " + field.getLength());
}

try {
  record = field.combine(value, record);
} catch (IllegalArgumentException e) {
  throw new IllegalStateException("bit-field overflow: " + e.getMessage(), e); // fail fast, never truncate
}

When it happens

Trigger: Calling combine() with a value exceeding the field width — e.g. a block size, storage policy id, or ACL/XAttr field whose numeric value needs more bits than the field's LENGTH, silently corrupting adjacent fields if unchecked. Hitting it from HDFS internals indicates a header layout change or a value that outgrew its field.

Common situations: Custom code reusing LongBitFormat with too-small LENGTH values; NameNode image/edition layouts where an added field squeezed others; direct experimentation with header formats.

Related errors

• Illagal value: {NAME} = {value} < MIN = {MIN}
• Unsupported protocol found when creating the proxy connectio
• Unknown nameservice: {}
• Configuration has multiple addresses that match local node's
• Cannot delete/rename non-empty protected directory {}

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