apache/hadoop · critical · IllegalStateException

serial id ${id} > ${maxEntryNumber}

Error message

serial id ${id} > ${maxEntryNumber}

What it means

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.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/SerialNumberManager.java:139

      throw new IllegalArgumentException(
        "String table bits " + bits + " > " + maskBits);
    }
    return new StringTable(size, bits);
  }

  public static class StringTable implements Iterable<Entry<Integer, String>> {
    private final int tableMaskBits;
    private final Map<Integer,String> map;

    private StringTable(int size, int loadingMaskBits) {
      this.tableMaskBits = loadingMaskBits;
      this.map = new HashMap<>(size);
    }

    private String get(SerialNumberManager snm, int id) {
      if (tableMaskBits != 0) {
        if (id > maxEntryNumber) {
          throw new IllegalStateException(
              "serial id " + id + " > " + maxEntryNumber);
        }
        id |= snm.getMask(tableMaskBits);
      }
      return map.get(id);
    }

    public void put(int id, String str) {
      map.put(id, str);
    }

    public Iterator<Entry<Integer, String>> iterator() {
      return map.entrySet().iterator();
    }

    public int size() {
      return map.size();
    }

View on GitHub (pinned to 2add963021)

Solutions

1. Discard the corrupt image and recover the NameNode from a known-good checkpoint or a peer node's storage (bootstrapStandby)
2. Verify integrity of copies with md5 (fsimage .md5 file) before using them
3. Inspect hardware/filesystem health on the volume that produced the file
4. If the image is from another cluster/version, load it with that exact Hadoop version instead

try {
  fsImage.loadFSImage(file, dstNamesystem);
} catch (IllegalStateException e) { // "serial id N > maxEntryNumber"
  // corrupt or foreign-format image: do not retry, restore a good checkpoint
  throw new IOException("Corrupt/incompatible fsimage " + file, e);
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• ${name}: serial number ${i} does not exist
• File " + url + " computed digest " + computedDigest + " does
• String table bits ${bits} > ${maskBits}
• ${name}: serial number map is full
• Expected to parse {} in parallel, but parsed {}. The image m

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