apache/hadoop · critical · IllegalStateException

${name}: serial number ${i} does not exist

Error message

${name}: serial number ${i} does not exist

What it means

The reverse lookup SerialNumberMap.get(int i) throws IllegalStateException when asked for a serial number that was never assigned (i2t miss). During fsimage load this means the serialized data references a serial id that the loaded string table does not contain — data that is internally inconsistent.

Source

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

          Integer old = t2i.putIfAbsent(t, sn);
          if (old != null) {
            current.getAndDecrement();
            return old;
          }
          i2t.put(sn, t);
        }
      }
    }
    return sn;
  }

  public T get(int i) {
    if (i == 0) {
      return null;
    }
    T t = i2t.get(i);
    if (t == null) {
      throw new IllegalStateException(
          name + ": serial number " + i + " does not exist");
    }
    return t;
  }

  int getMax() {
    return max;
  }

  Set<Map.Entry<Integer, T>> entrySet() {
    return new HashSet<>(i2t.entrySet());
  }

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

  @Override

View on GitHub (pinned to 2add963021)

Solutions

1. Restore from a consistent checkpoint or bootstrap the node from a healthy peer's storage
2. Validate the fsimage .md5 checksum before every manual copy or restore
3. Never hand-mix fsimage/edits files from different directories or clusters; recover via -bootstrapStandby or a full checkpoint instead
4. Check the underlying volume/filesystem for errors (dmesg, smartctl, storage logs)

try {
  fsImage.loadFSImage(file, dstNamesystem);
} catch (IllegalStateException e) { // "serial number N does not exist"
  // internally inconsistent image — fall back to previous good checkpoint
  // or bootstrap from peer; do not attempt partial recovery
}

When it happens

Trigger: Image load or edits replay calls getString(id)/get(i) with an id that has no entry: truncated string-table section, an fsimage paired with edits/alias data from a different namespace, or bit-corrupted id fields.

Common situations: Mixing storage files from two clusters or two layout generations during manual recovery; image copied incompletely (network/disk interruption); NameNode storage damaged by a failing disk.

Related errors

• serial id ${id} > ${maxEntryNumber}
• ${name}: serial number map is full
• All negative block group IDs are used, growing into positive
• All positive block IDs are used, wrapping to negative IDs, w
• Unknown nameservice: {}

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