{"record":{"id":"07c58c5d0c913822","repo":"apache/hadoop","slug":"bug-the-stored-lv-is-newer-than-the-supporte","errorCode":null,"errorMessage":"BUG: The stored LV = {} is newer than the supported LV = {}","messagePattern":"BUG: The stored LV = (.+?) is newer than the supported LV = (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DataStorage.java","lineNumber":777,"sourceCode":"    }\n\n    // do upgrade\n    if (this.layoutVersion > DataNodeLayoutVersion.getCurrentLayoutVersion()) {\n      if (federationSupported) {\n        // If the existing on-disk layout version supports federation,\n        // simply update the properties.\n        upgradeProperties(sd, conf);\n      } else {\n        doUpgradePreFederation(sd, nsInfo, callables, conf);\n      }\n      return true; // doUgrade already has written properties\n    }\n    \n    // layoutVersion < DATANODE_LAYOUT_VERSION. I.e. stored layout version is newer\n    // than the version supported by datanode. This should have been caught\n    // in readProperties(), even if rollback was not carried out or somehow\n    // failed.\n    throw new IOException(\"BUG: The stored LV = \" + this.getLayoutVersion()\n        + \" is newer than the supported LV = \"\n        + DataNodeLayoutVersion.getCurrentLayoutVersion());\n  }\n\n  /**\n   * Upgrade from a pre-federation layout.\n   * Move current storage into a backup directory,\n   * and hardlink all its blocks into the new current directory.\n   * \n   * Upgrade from pre-0.22 to 0.22 or later release e.g. 0.19/0.20/ => 0.22/0.23\n   * <ul>\n   * <li> If <SD>/previous exists then delete it </li>\n   * <li> Rename <SD>/current to <SD>/previous.tmp </li>\n   * <li>Create new <SD>/current/<bpid>/current directory<li>\n   * <ul>\n   * <li> Hard links for block files are created from <SD>/previous.tmp \n   * to <SD>/current/<bpid>/current </li>\n   * <li> Saves new version file in <SD>/current/<bpid>/current directory </li>","sourceCodeStart":759,"sourceCodeEnd":795,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DataStorage.java#L759-L795","documentation":"After readProperties and the upgrade branches, the only remaining possibility is a stored layoutVersion numerically smaller (i.e. newer) than DataNodeLayoutVersion.getCurrentLayoutVersion(). HDFS storage is forward-only, so this state - which checkVersionUpgradable during readProperties should normally have caught - is reported as a BUG: the running datanode binary is older than its on-disk metadata.","triggerScenarios":"Starting an older Hadoop distribution against storage written by a newer version - e.g. rolling back the installed package after an upgrade, or a stale install path shadowing the new one - so stored LV < supported LV slips past the earlier checks.","commonSituations":"Package downgrade after a failed upgrade; alternates symlink still pointing at the old Hadoop release; test clusters flipping between versions without matching storage.","solutions":["Upgrade the datanode software to at least the version that wrote the storage (match 'hadoop version' across the cluster)","Never downgrade HDFS metadata; to revert an upgrade use 'hdfs datanode -rollback' while binaries still match, restoring the previous snapshot","Verify the layoutVersion inside <dataDir>/current/VERSION against the active binary's supported layout"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"# before starting the DN, ensure the binary is not older than the stored layout\nhadoop version\nLV_STORED=$(grep '^layoutVersion=' $DATA_DIR/current/VERSION | cut -d= -f2)\n# compare with the layout version supported by this release\n# (org.apache.hadoop.hdfs.server.datanode.DataNodeLayoutVersion)\n# if LV_STORED is numerically SMALLER than supported, this binary is too old -> upgrade first","typeGuard":null,"tryCatchPattern":"catch (IOException e) {\n  if (String.valueOf(e.getMessage()).contains(\"is newer than the supported LV\")) {\n    // on-disk metadata is newer than the binary: upgrade the Hadoop install; never downgrade storage\n  } else { throw e; }\n}","preventionTips":["Keep 'hadoop version' identical cluster-wide; verify before and after package changes","After any upgrade, pin the package version so hosts cannot silently fall back","If a revert is truly needed, use -rollback while the new binaries are still installed"],"tags":["hadoop","hdfs","datanode","storage","layout-version","downgrade","version-mismatch"],"backgroundTag":"software-version-downgrade-unsupported","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}