apache/hadoop · critical · IncorrectVersionException

Unexpected version of storage directory {path}. Reported: {r

Error message

Unexpected version of storage directory {path}. Reported: {reported}. Expecting = {expected}.

What it means

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>.'

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/common/StorageInfo.java:220

      StorageDirectory sd) throws InconsistentFSStateException {
    // Set cluster ID in version that supports federation
    if (LayoutVersion.supports(getServiceLayoutFeatureMap(),
        Feature.FEDERATION, layoutVersion)) {
      String cid = getProperty(props, sd, "clusterID");
      if (!(clusterID.equals("") || cid.equals("") || clusterID.equals(cid))) {
        throw new InconsistentFSStateException(sd.getRoot(),
            "cluster Id is incompatible with others.");
      }
      clusterID = cid;
    }
  }
  
  /** Validate and set layout version from {@link Properties}*/
  protected void setLayoutVersion(Properties props, StorageDirectory sd)
      throws IncorrectVersionException, InconsistentFSStateException {
    int lv = Integer.parseInt(getProperty(props, sd, "layoutVersion"));
    if (lv < getServiceLayoutVersion()) { // future version
      throw new IncorrectVersionException(getServiceLayoutVersion(), lv,
          "storage directory " + sd.root.getAbsolutePath());
    }
    layoutVersion = lv;
  }
  
  /** Validate and set namespaceID version from {@link Properties}*/
  protected void setNamespaceID(Properties props, StorageDirectory sd)
      throws InconsistentFSStateException {
    int nsId = Integer.parseInt(getProperty(props, sd, "namespaceID"));
    if (namespaceID != 0 && nsId != 0 && namespaceID != nsId) {
      throw new InconsistentFSStateException(sd.root,
          "namespaceID is incompatible with others.");
    }
    namespaceID = nsId;
  }

  public void setServiceLayoutVersion(int lv) {
    this.layoutVersion = lv;

View on GitHub (pinned to 2add963021)

Solutions

1. Restart with the newer (or equal) Hadoop release that wrote the storage
2. If rollback was intended, roll back to the saved pre-upgrade snapshot pair rather than pointing an old binary at new-format storage
3. As a last resort, back up and reformat (destroys the namespace)

Properties p = Storage.readPropertiesFile(new File(dir, "VERSION"));
int lv = Integer.parseInt(p.getProperty("layoutVersion"));
int current = HdfsServerConstants.NAMENODE_LAYOUT_VERSION;
if (lv < current) {
  throw new IOException(dir + " written by newer software (layout " + lv
      + " < " + current + "); downgrade unsupported");
}

try {
  cluster.start();
} catch (IncorrectVersionException e) {
  // storage layout is newer than the binary: deploy the matching release instead of retrying
  throw e;
}

When it happens

Trigger: 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.

Common situations: Downgrade attempts after a failed upgrade; someone reinstalled an older Hadoop RPM/deb; NN and BN on divergent versions sharing dirs.

Related errors

• BUG: The stored LV = {} is newer than the supported LV = {}
• Found feature flags which we can't handle. Please upgrade yo
• Unexpected FS state: {curState} for storage directory: {root
• *********** Upgrade is not supported from this older versio
• Unexpected version of the file system log file: logVersion.

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