apache/hadoop · error · IOException

Cannot rollback to storage version {prevStorage.getLayoutVer

Error message

Cannot rollback to storage version {prevStorage.getLayoutVersion()} using this version of the NameNode, which uses storage version {targetLayoutVersion}. Please use the previous version of HDFS to perform the rollback.

What it means

Thrown by NNUpgradeUtil.doRollback when the layout version recorded in the storage directory's 'previous' directory does not equal targetLayoutVersion, the layout version implemented by the running NameNode binary. HDFS changes its on-disk storage layout between releases, so a rollback must be executed by the exact software version that wrote the 'previous' snapshot. This check refuses the rollback instead of corrupting metadata with an incompatible reader/writer.

Source

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

   * @return true if this JM can roll back, false otherwise.
   * @throws IOException in the event of error
   */
  static boolean canRollBack(StorageDirectory sd, StorageInfo storage,
      StorageInfo prevStorage, int targetLayoutVersion) throws IOException {
    File prevDir = sd.getPreviousDir();
    if (!prevDir.exists()) {  // use current directory then
      LOG.info("Storage directory " + sd.getRoot()
               + " does not contain previous fs state.");
      // read and verify consistency with other directories
      storage.readProperties(sd);
      return false;
    }

    // read and verify consistency of the prev dir
    prevStorage.readPreviousVersionProperties(sd);

    if (prevStorage.getLayoutVersion() != targetLayoutVersion) {
      throw new IOException(
        "Cannot rollback to storage version " +
        prevStorage.getLayoutVersion() +
        " using this version of the NameNode, which uses storage version " +
        targetLayoutVersion + ". " +
        "Please use the previous version of HDFS to perform the rollback.");
    }
    
    return true;
  }

  /**
   * Finalize the upgrade. The previous dir, if any, will be renamed and
   * removed. After this is completed, rollback is no longer allowed.
   * 
   * @param sd the storage directory to finalize
   * @throws IOException in the event of error
   */
  static void doFinalize(StorageDirectory sd) throws IOException {

View on GitHub (pinned to 2add963021)

Solutions

Reinstall the exact Hadoop/HDFS distribution that performed the upgrade (the one that created the 'previous' directory) and run 'hdfs namenode -rollback' with it on every NameNode/storage directory.
If you no longer want to roll back, finalize instead: 'hdfs dfsadmin -finalizeUpgrade' removes the incompatible 'previous' directory.
Before retrying, compare layoutVersion in the VERSION file under the 'previous' dir with the layout version of the installed software (checked in on startup) to confirm which build you need.
If the previous state is unusable and rollback is impossible, restore the namespace from a checkpoint/backup or reformat (data loss - last resort).

Example fix

// before
hdfs namenode -rollback   # run with newer binaries than the ones that wrote 'previous'

// after
# identify the layout the rollback target uses
grep layoutVersion /data/dfs/name/previous/VERSION
# run the rollback with the exact pre-upgrade Hadoop distribution
<extract that distribution and put it on PATH>
hdfs namenode -rollback

Defensive patterns

Strategy: validation

Validate before calling

# before issuing 'hdfs namenode -rollback', verify the previous layout matches the installed software
prev=$(grep '^layoutVersion' /data/dfs/name/previous/VERSION 2>/dev/null | cut -d= -f2)
if [ -z "$prev" ]; then echo "no previous dir - nothing to roll back"; exit 0; fi
if [ "$prev" != "$(hdfs namenode -metadataVersion 2>/dev/null | awk '/layoutVersion/ {print $NF}')" ]; then
  echo "layout mismatch: previous=$prev - use the Hadoop version that wrote 'previous'"
  exit 1
fi
hdfs namenode -rollback

Prevention

Keep the pre-upgrade Hadoop distribution installed (or its tarball archived) on every NN host until the upgrade is finalized.
Always finalize ('hdfs dfsadmin -finalizeUpgrade') after the commit window so a stale incompatible 'previous' dir can never collide with a later rollback.
Document the exact distribution/version used for each upgrade so the rollback binary is unambiguous.

When it happens

Trigger: Running 'hdfs namenode -rollback' (or starting the NN with -rollback) after doPreUpgrade/upgrade when prevStorage.readPreviousVersionProperties(sd) reports a layoutVersion different from the current binary's targetLayoutVersion. Typical when binaries were swapped again after the upgrade, so the installed software no longer matches the version that created 'previous'.

Common situations: Upgraded 3.3.x -> 3.4.x, then downgraded binaries further before rolling back; attempting rollback with a different vendor distribution than the one that upgraded the cluster; a stale 'previous' directory left over from an older upgrade cycle.

Related errors

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