{"record":{"id":"6b3af30db858be03","repo":"apache/hadoop","slug":"serial-id-id-maxentrynumber","errorCode":null,"errorMessage":"serial id ${id} > ${maxEntryNumber}","messagePattern":"serial id (.+?) > (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/SerialNumberManager.java","lineNumber":139,"sourceCode":"      throw new IllegalArgumentException(\n        \"String table bits \" + bits + \" > \" + maskBits);\n    }\n    return new StringTable(size, bits);\n  }\n\n  public static class StringTable implements Iterable<Entry<Integer, String>> {\n    private final int tableMaskBits;\n    private final Map<Integer,String> map;\n\n    private StringTable(int size, int loadingMaskBits) {\n      this.tableMaskBits = loadingMaskBits;\n      this.map = new HashMap<>(size);\n    }\n\n    private String get(SerialNumberManager snm, int id) {\n      if (tableMaskBits != 0) {\n        if (id > maxEntryNumber) {\n          throw new IllegalStateException(\n              \"serial id \" + id + \" > \" + maxEntryNumber);\n        }\n        id |= snm.getMask(tableMaskBits);\n      }\n      return map.get(id);\n    }\n\n    public void put(int id, String str) {\n      map.put(id, str);\n    }\n\n    public Iterator<Entry<Integer, String>> iterator() {\n      return map.entrySet().iterator();\n    }\n\n    public int size() {\n      return map.size();\n    }","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/SerialNumberManager.java#L121-L157","documentation":"While reading the fsimage string table, StringTable.get() sanity-checks every serial id decoded from serialized permission/ACL/xattr fields: if tableMaskBits != 0 and id exceeds maxEntryNumber (2^29-1), it throws IllegalStateException. An id above the maximum cannot be produced by a legitimate writer of this layout, so this signals corrupt or foreign-format data.","triggerScenarios":"Image load (StringTable.get(snm, id)) after newStringTable() accepted the header but individual entries reference out-of-range ids — truncated image tail, bit-flipped txid/id fields, or an image whose layout assumptions differ from the reader.","commonSituations":"fsimage corrupted by disk failure or an interrupted/non-atomic copy; partial image left after a crashed checkpoint being used for recovery; mismatched fsimage/edits stitched together from different sources.","solutions":["Discard the corrupt image and recover the NameNode from a known-good checkpoint or a peer node's storage (bootstrapStandby)","Verify integrity of copies with md5 (fsimage .md5 file) before using them","Inspect hardware/filesystem health on the volume that produced the file","If the image is from another cluster/version, load it with that exact Hadoop version instead"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  fsImage.loadFSImage(file, dstNamesystem);\n} catch (IllegalStateException e) { // \"serial id N > maxEntryNumber\"\n  // corrupt or foreign-format image: do not retry, restore a good checkpoint\n  throw new IOException(\"Corrupt/incompatible fsimage \" + file, e);\n}","preventionTips":["Always verify the fsimage .md5 companion file after copying images around","Keep at least two retained checkpoints so a corrupt newest image can be skipped","Use -bootstrapStandby from a healthy peer instead of hand-copied image files"],"tags":["hdfs","fsimage","serial-number","data-corruption","image-load","illegal-state"],"backgroundTag":"data-corruption","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}