{"record":{"id":"b9bf55b9ba0f5551","repo":"apache/hadoop","slug":"directory-dir-is-in-an-inconsistent-state-previ","errorCode":null,"errorMessage":"Directory {dir} is in an inconsistent state: previous fs state should not exist during upgrade. Finalize or rollback first.","messagePattern":"Directory (.+?) is in an inconsistent state: previous fs state should not exist during upgrade\\. Finalize or rollback first\\.","errorType":"exception","errorClass":"org.apache.hadoop.hdfs.server.common.InconsistentFSStateException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImage.java","lineNumber":428,"sourceCode":"          throw new IOException(\"Cannot import image from a checkpoint. \" \n              + \" NameNode already contains an image in \" + sd.getRoot());\n      } catch (IOException ioe) {\n        sd.unlock();\n        throw ioe;\n      }\n      dataDirStates.put(sd,curState);\n    }\n    return isFormatted;\n  }\n\n  /** Check if upgrade is in progress. */\n  public static void checkUpgrade(NNStorage storage) throws IOException {\n    // Upgrade or rolling upgrade is allowed only if there are \n    // no previous fs states in any of the local directories\n    for (Iterator<StorageDirectory> it = storage.dirIterator(false); it.hasNext();) {\n      StorageDirectory sd = it.next();\n      if (sd.getPreviousDir().exists())\n        throw new InconsistentFSStateException(sd.getRoot(),\n            \"previous fs state should not exist during upgrade. \"\n            + \"Finalize or rollback first.\");\n    }\n  }\n\n  void checkUpgrade() throws IOException {\n    checkUpgrade(storage);\n  }\n\n  /**\n   * @return true if there is rollback fsimage (for rolling upgrade) in NameNode\n   * directory.\n   */\n  public boolean hasRollbackFSImage() throws IOException {\n    final FSImageStorageInspector inspector = new FSImageTransactionalStorageInspector(\n        EnumSet.of(NameNodeFile.IMAGE_ROLLBACK));\n    storage.inspectStorageDirs(inspector);\n    try {","sourceCodeStart":410,"sourceCodeEnd":446,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImage.java#L410-L446","documentation":"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.","triggerScenarios":"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.","commonSituations":"Interrupted upgrades; repeated upgrade attempts; a rolling upgrade left unfinalized followed by an attempted regular upgrade.","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."],"exampleFix":"# before\nhdfs --daemon start namenode -upgrade\n# InconsistentFSStateException: previous fs state should not exist during upgrade.\n\n# after\nhdfs dfsadmin -fs nn.example.com:8020 -finalizeUpgrade\nhdfs --daemon start namenode -upgrade","handlingStrategy":"validation","validationCode":"for (URI u : nameDirs) {\n  if (Files.exists(Paths.get(u.getPath(), \"previous\"))) {\n    throw new IllegalStateException(\n        \"previous/ exists in \" + u + \" — finalize or rollback before upgrading\");\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always finalize (or roll back) after each upgrade window closes.","Monitor for lingering previous/ directories after upgrades.","Automate finalize in the upgrade runbook."],"tags":["hdfs","namenode","upgrade","finalize","rollback"],"backgroundTag":"upgrade-state-conflict","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}