apache/hadoop · error · org.apache.hadoop.hdfs.server.common.InconsistentFSStateException

Directory {dir} is in an inconsistent state: previous fs sta

Error message

Directory {dir} is in an inconsistent state: previous fs state should not exist during upgrade. Finalize or rollback first.

What it means

checkUpgrade() enforces that no storage directory contains a 'previous/' snapshot (retained pre-upgrade state) before a new upgrade may begin. Finding one means an earlier upgrade was never finalized or rolled back, and stacking a second pending upgrade state on top is unsupported, so InconsistentFSStateException is thrown.

Source

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

          throw new IOException("Cannot import image from a checkpoint. " 
              + " NameNode already contains an image in " + sd.getRoot());
      } catch (IOException ioe) {
        sd.unlock();
        throw ioe;
      }
      dataDirStates.put(sd,curState);
    }
    return isFormatted;
  }

  /** Check if upgrade is in progress. */
  public static void checkUpgrade(NNStorage storage) throws IOException {
    // Upgrade or rolling upgrade is allowed only if there are 
    // no previous fs states in any of the local directories
    for (Iterator<StorageDirectory> it = storage.dirIterator(false); it.hasNext();) {
      StorageDirectory sd = it.next();
      if (sd.getPreviousDir().exists())
        throw new InconsistentFSStateException(sd.getRoot(),
            "previous fs state should not exist during upgrade. "
            + "Finalize or rollback first.");
    }
  }

  void checkUpgrade() throws IOException {
    checkUpgrade(storage);
  }

  /**
   * @return true if there is rollback fsimage (for rolling upgrade) in NameNode
   * directory.
   */
  public boolean hasRollbackFSImage() throws IOException {
    final FSImageStorageInspector inspector = new FSImageTransactionalStorageInspector(
        EnumSet.of(NameNodeFile.IMAGE_ROLLBACK));
    storage.inspectStorageDirs(inspector);
    try {

View on GitHub (pinned to 2add963021)

Solutions

Finalize the pending state first: hdfs dfsadmin -fs <namenode> -finalizeUpgrade (for rolling upgrades: hdfs dfsadmin -rollingUpgrade finalize).
Or revert instead: 'hdfs namenode -rollback' returns to the previous/ state and removes it.
Then retry the upgrade.
Last resort on a NameNode that cannot start: manually archive previous/ away only after taking full metadata backups.

Example fix

# before
hdfs --daemon start namenode -upgrade
# InconsistentFSStateException: previous fs state should not exist during upgrade.

# after
hdfs dfsadmin -fs nn.example.com:8020 -finalizeUpgrade
hdfs --daemon start namenode -upgrade

Defensive patterns

Strategy: validation

Validate before calling

for (URI u : nameDirs) {
  if (Files.exists(Paths.get(u.getPath(), "previous"))) {
    throw new IllegalStateException(
        "previous/ exists in " + u + " — finalize or rollback before upgrading");
  }
}

Prevention

Always finalize (or roll back) after each upgrade window closes.
Monitor for lingering previous/ directories after upgrades.
Automate finalize in the upgrade runbook.

When it happens

Trigger: Starting 'hdfs namenode -upgrade' when previous/ exists in any name dir; a previous upgrade crashed midway and was never finalized; operator forgot 'hdfs dfsadmin -finalizeUpgrade' after the last upgrade window.

Common situations: Interrupted upgrades; repeated upgrade attempts; a rolling upgrade left unfinalized followed by an attempted regular upgrade.

Related errors

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