apache/hadoop · error · IllegalArgumentException

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

Error message

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

What it means

LongBitFormat packs named bit fields into a single 64-bit long (used by NameNode header formats such as INodeFile.HeaderFormat, AclEntryStatusFormat, XAttrFormat, and PipelineAck.StatusFormat). combine(value, record) validates that value fits [MIN, MAX] for the field before splicing it in; this IllegalArgumentException (message contains the source typo 'Illagal') fires when value < MIN. MIN is 0 for most fields, so in practice this is a negative value being packed.

Source

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

  public LongBitFormat(String name, LongBitFormat previous, int length,
                       long min) {
    NAME = name;
    OFFSET = previous == null? 0: previous.OFFSET + previous.LENGTH;
    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. Range-check the value against the field before packing: reject value < BITS.getMin() (and > MAX) with your own clearer error
2. If seen inside a NameNode without custom code, capture the field NAME from the message and check for version skew or patches on INode serialization; report with logs

Example fix

// before
long header = HeaderFormat.REPLICATION.combine(-1, header);

// after
if (replication < HeaderFormat.REPLICATION.getMin()) {
  throw new IllegalArgumentException("replication out of range: " + replication);
}
long header = HeaderFormat.REPLICATION.combine(replication, header);

long v = valueToPack;
if (v < field.getMin() || v > field.retrieve(-1L)) {
  throw new IllegalArgumentException(field.getName() + " value " + v + " outside packable range");
}
long record2 = field.combine(v, record);

try {
  record = field.combine(v, record);
} catch (IllegalArgumentException e) {
  // message has field NAME and bounds; treat as programmer error, do not retry
  throw new IllegalStateException("bit-field packing invariant broken: " + e.getMessage(), e);
}

When it happens

Trigger: Calling LongBitFormat.combine() with a negative value — e.g. packing a negative replication, storage policy id, or block size into an INodeFile header. Not reachable from normal HDFS client APIs; surfaces via direct use of the class or internal NameNode code paths passing an out-of-range field.

Common situations: Custom tooling or tests that build inode headers / pipeline acks by hand; NameNode invariant violations where an unset (-1 sentinel) field leaks into combine().

Related errors

• Illagal value: ${NAME} = ${value} < MIN = ${MIN}
• Unsupported protocol found when creating the proxy connectio
• Unknown OpenFileType: {}
• Unknown nameservice: {}
• Configuration has multiple addresses that match local node's

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