{"record":{"id":"ac08a21a543a669a","repo":"apache/hadoop","slug":"unexpected-version-of-storage-directory-path-re","errorCode":null,"errorMessage":"Unexpected version of storage directory {path}. Reported: {reported}. Expecting = {expected}.","messagePattern":"Unexpected version of storage directory (.+?)\\. Reported: (.+?)\\. Expecting = (.+?)\\.","errorType":"exception","errorClass":"IncorrectVersionException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/common/StorageInfo.java","lineNumber":220,"sourceCode":"      StorageDirectory sd) throws InconsistentFSStateException {\n    // Set cluster ID in version that supports federation\n    if (LayoutVersion.supports(getServiceLayoutFeatureMap(),\n        Feature.FEDERATION, layoutVersion)) {\n      String cid = getProperty(props, sd, \"clusterID\");\n      if (!(clusterID.equals(\"\") || cid.equals(\"\") || clusterID.equals(cid))) {\n        throw new InconsistentFSStateException(sd.getRoot(),\n            \"cluster Id is incompatible with others.\");\n      }\n      clusterID = cid;\n    }\n  }\n  \n  /** Validate and set layout version from {@link Properties}*/\n  protected void setLayoutVersion(Properties props, StorageDirectory sd)\n      throws IncorrectVersionException, InconsistentFSStateException {\n    int lv = Integer.parseInt(getProperty(props, sd, \"layoutVersion\"));\n    if (lv < getServiceLayoutVersion()) { // future version\n      throw new IncorrectVersionException(getServiceLayoutVersion(), lv,\n          \"storage directory \" + sd.root.getAbsolutePath());\n    }\n    layoutVersion = lv;\n  }\n  \n  /** Validate and set namespaceID version from {@link Properties}*/\n  protected void setNamespaceID(Properties props, StorageDirectory sd)\n      throws InconsistentFSStateException {\n    int nsId = Integer.parseInt(getProperty(props, sd, \"namespaceID\"));\n    if (namespaceID != 0 && nsId != 0 && namespaceID != nsId) {\n      throw new InconsistentFSStateException(sd.root,\n          \"namespaceID is incompatible with others.\");\n    }\n    namespaceID = nsId;\n  }\n\n  public void setServiceLayoutVersion(int lv) {\n    this.layoutVersion = lv;","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/common/StorageInfo.java#L202-L238","documentation":"StorageInfo.setLayoutVersion parses layoutVersion from VERSION and throws IncorrectVersionException when the stored value is less than the running software's layout version. Layout versions count downwards (newer layouts are more negative), so a lower value means the directory was written by a NEWER Hadoop release - and downgrade is not supported. The message is built by IncorrectVersionException(int, String, int): 'Unexpected version of storage directory <path>. Reported: <lv>. Expecting = <current>.'","triggerScenarios":"Starting an older Hadoop binary against storage written by a newer release; rolling back a rolling upgrade without using the saved pre-upgrade snapshot; a newer DataNode/2NN wrote the VERSION file and an older daemon then reads it; mixed-version cluster with dirs on shared storage.","commonSituations":"Downgrade attempts after a failed upgrade; someone reinstalled an older Hadoop RPM/deb; NN and BN on divergent versions sharing dirs.","solutions":["Restart with the newer (or equal) Hadoop release that wrote the storage","If rollback was intended, roll back to the saved pre-upgrade snapshot pair rather than pointing an old binary at new-format storage","As a last resort, back up and reformat (destroys the namespace)"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"Properties p = Storage.readPropertiesFile(new File(dir, \"VERSION\"));\nint lv = Integer.parseInt(p.getProperty(\"layoutVersion\"));\nint current = HdfsServerConstants.NAMENODE_LAYOUT_VERSION;\nif (lv < current) {\n  throw new IOException(dir + \" written by newer software (layout \" + lv\n      + \" < \" + current + \"); downgrade unsupported\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  cluster.start();\n} catch (IncorrectVersionException e) {\n  // storage layout is newer than the binary: deploy the matching release instead of retrying\n  throw e;\n}","preventionTips":["Pin a single Hadoop version across daemons that share storage directories","Never downgrade binaries over upgraded storage; roll back via the saved pre-upgrade snapshot","Compare layoutVersion in VERSION against the binary's constant during pre-deploy checks"],"tags":["hdfs","layout-version","downgrade","version-mismatch","storage"],"backgroundTag":"version-downgrade-unsupported","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}