apache/hadoop · critical · OutOfLegacyGenerationStampsException

Out of V1 (legacy) generation stamps

Error message

Out of V1 (legacy) generation stamps

What it means

BlockIdManager reserves a finite range for 'legacy' generation stamps used by blocks created before sequential block IDs (ancient HDFS upgrades). getNextLegacyGenerationStamp calls legacyGenerationStamp.nextValue() and throws OutOfLegacyGenerationStampsException ('Out of V1 (legacy) generation stamps') when the value reaches legacyGenerationStampLimit. After that, no new stamp can be minted for legacy blocks, so appends and lease/replica recovery on those blocks fail. The comment in code notes this is extremely unlikely since 1T stamps are reserved.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/blockmanagement/BlockIdManager.java:232

  /**
   * Increments, logs and then returns the stamp
   */
  long nextGenerationStamp(boolean legacyBlock) throws IOException {
    return legacyBlock ? getNextLegacyGenerationStamp() :
        getNextGenerationStamp();
  }

  @VisibleForTesting
  long getNextLegacyGenerationStamp() throws IOException {
    long legacyGenStamp = legacyGenerationStamp.nextValue();

    if (legacyGenStamp >= legacyGenerationStampLimit) {
      // We ran out of generation stamps for legacy blocks. In practice, it
      // is extremely unlikely as we reserved 1T legacy generation stamps. The
      // result is that we can no longer append to the legacy blocks that
      // were created before the upgrade to sequential block IDs.
      throw new OutOfLegacyGenerationStampsException();
    }

    return legacyGenStamp;
  }

  @VisibleForTesting
  long getNextGenerationStamp() {
    return generationStamp.nextValue();
  }

  public long getLegacyGenerationStampLimit() {
    return legacyGenerationStampLimit;
  }

  /**
   * Determine whether the block ID was randomly generated (legacy) or
   * sequentially generated. The generation stamp value is used to
   * make the distinction.

View on GitHub (pinned to 2add963021)

Solutions

1. Identify the legacy blocks (hdfs fsck output marks ancient blocks; check block IDs below the legacy threshold) and rewrite their containing files - distcp them to new files and delete the originals so they get new-style block IDs
2. Stop append-heavy jobs against the very old files until they are migrated
3. Engage the Hadoop community with the NameNode logs - there is no configuration to enlarge the reserved range

Example fix

# migrate ancient files so blocks get new-style IDs
hadoop distcp hdfs://nn/legacy/path hdfs://nn/legacy/path.v2
hdfs dfs -rm -r -skipTrash hdfs://nn/legacy/path
hdfs dfs -mv hdfs://nn/legacy/path.v2 hdfs://nn/legacy/path

try { stamp = blockIdManager.getNextGenerationStamp(isLegacyBlock); }
catch (OutOfLegacyGenerationStampsException e) { LOG.error("Legacy generation stamp space exhausted; migrate legacy blocks"); alertOps(); throw e; }

When it happens

Trigger: A cluster carrying blocks created by pre-sequential-block-ID HDFS versions, combined with ~2^40 append/lease-recovery operations incrementing legacy generation stamps until the reserved range is exhausted.

Common situations: Effectively unreachable in practice; would require a decades-old migrated namespace under continuous append/recovery churn. Newer clusters never have legacy blocks, so any occurrence points to extraordinary history or corrupted counter state.

Related errors

• Trying to commit inconsistent block: id = {blockId}, expecte
• Commit block with mismatching GS. NN has {block}, client sub
• Mismatched block IDs or generation stamps for the old last b
• Mismatched block IDs or generation stamps, attempting to rep
• The recovery id {} does not match current recovery id {} for

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