{"record":{"id":"84156672972baa68","repo":"apache/hadoop","slug":"illagal-value-name-value-min-min","errorCode":null,"errorMessage":"Illagal value: {NAME} = {value} < MIN = {MIN}","messagePattern":"Illagal value: (.+?) = (.+?) < MIN = (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/util/LongBitFormat.java","lineNumber":63,"sourceCode":"  public LongBitFormat(String name, LongBitFormat previous, int length,\n                       long min) {\n    NAME = name;\n    OFFSET = previous == null? 0: previous.OFFSET + previous.LENGTH;\n    LENGTH = length;\n    MIN = min;\n    MAX = ((-1L) >>> (64 - LENGTH));\n    MASK = MAX << OFFSET;\n  }\n\n  /** Retrieve the value from the record. */\n  public long retrieve(long record) {\n    return (record & MASK) >>> OFFSET;\n  }\n\n  /** Combine the value to the record. */\n  public long combine(long value, long record) {\n    if (value < MIN) {\n      throw new IllegalArgumentException(\n          \"Illagal value: \" + NAME + \" = \" + value + \" < MIN = \" + MIN);\n    }\n    if (value > MAX) {\n      throw new IllegalArgumentException(\n          \"Illagal value: \" + NAME + \" = \" + value + \" > MAX = \" + MAX);\n    }\n    return (record & ~MASK) | (value << OFFSET);\n  }\n\n  public long getMin() {\n    return MIN;\n  }\n\n  public int getLength() {\n    return LENGTH;\n  }\n}\n","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/util/LongBitFormat.java#L45-L81","documentation":"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.","triggerScenarios":"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.","commonSituations":"Custom tooling or tests that build inode headers / pipeline acks by hand; NameNode invariant violations where an unset (-1 sentinel) field leaks into combine().","solutions":["Range-check the value against the field before packing: reject value < BITS.getMin() (and > MAX) with your own clearer error","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"],"exampleFix":"// before\nlong header = HeaderFormat.REPLICATION.combine(-1, header);\n\n// after\nif (replication < HeaderFormat.REPLICATION.getMin()) {\n  throw new IllegalArgumentException(\"replication out of range: \" + replication);\n}\nlong header = HeaderFormat.REPLICATION.combine(replication, header);","handlingStrategy":"validation","validationCode":"long v = valueToPack;\nif (v < field.getMin() || v > field.retrieve(-1L)) {\n  throw new IllegalArgumentException(field.getName() + \" value \" + v + \" outside packable range\");\n}\nlong record2 = field.combine(v, record);","typeGuard":null,"tryCatchPattern":"try {\n  record = field.combine(v, record);\n} catch (IllegalArgumentException e) {\n  // message has field NAME and bounds; treat as programmer error, do not retry\n  throw new IllegalStateException(\"bit-field packing invariant broken: \" + e.getMessage(), e);\n}","preventionTips":["Treat combine() arguments as trusted-range values; validate at the source API, not at packing time","Watch for -1 sentinels from finders/parsers leaking into header fields"],"tags":["hdfs","namenode","bit-packing","internal-api","illegal-argument"],"backgroundTag":"value-out-of-range","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}