What causes "file VERSION is invalid." in apache/hadoop?

Restore the VERSION file from backup or from the sibling block-pool storage copies

apache/hadoop · error · InconsistentFSStateException

file VERSION is invalid.

Error message

file VERSION is invalid.

What it means

While reading a pre-federation storage directory's VERSION file, DataStorage requires a storageID property. If props.getProperty("storageID") is null the file is malformed/incomplete for its layout version, and InconsistentFSStateException ('file VERSION is invalid.') aborts use of that directory.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/DataStorage.java:647

      this.layoutVersion = toLayoutVersion;
    } else {
      setLayoutVersion(props, sd);
    }
    setcTime(props, sd);
    checkStorageType(props, sd);
    setClusterId(props, layoutVersion, sd);
    
    // Read NamespaceID in version before federation
    if (!DataNodeLayoutVersion.supports(
        LayoutVersion.Feature.FEDERATION, layoutVersion)) {
      setNamespaceID(props, sd);
    }
    

    // valid storage id, storage id may be empty
    String ssid = props.getProperty("storageID");
    if (ssid == null) {
      throw new InconsistentFSStateException(sd.getRoot(), "file "
          + STORAGE_FILE_VERSION + " is invalid.");
    }
    String sid = sd.getStorageUuid();
    if (!(sid == null || sid.equals("") ||
          ssid.equals("") || sid.equals(ssid))) {
      throw new InconsistentFSStateException(sd.getRoot(),
          "has incompatible storage Id.");
    }

    if (sid == null) { // update id only if it was null
      sd.setStorageUuid(ssid);
    }

    // Update the datanode UUID if present.
    if (props.getProperty("datanodeUuid") != null) {
      String dnUuid = props.getProperty("datanodeUuid");

      if (getDatanodeUuid() == null) {

View on GitHub (pinned to 2add963021)

Solutions

Restore the VERSION file from backup or from the sibling block-pool storage copies
If the directory's data is dispensable, remove/reformat the directory so the DN recreates it cleanly
Never hand-edit VERSION; manage DN storage only through Hadoop tooling

Defensive patterns

Strategy: validation

Validate before calling

Properties props = new Properties();
try (Reader r = Files.newBufferedReader(dir.resolve("current/VERSION"))) {
  props.load(r);
}
if (props.getProperty("storageID") == null) {
  throw new IOException("VERSION file invalid (no storageID): " + dir);
}

Try / catch

catch (InconsistentFSStateException e) {
  // VERSION malformed: restore from backup or reformat the directory
  logAndHaltStartupWithGuidance(e);
}

Prevention

Keep backups of VERSION files (or whole metadata dirs) before maintenance on old clusters
Use only Hadoop tooling to format/rollback storage; never script edits to VERSION
After crashes, validate all VERSION files parse completely before restarting

When it happens

Trigger: A pre-federation data dir whose VERSION file lacks the storageID line - truncated write from a crash, manual editing, or a VERSION produced by non-Hadoop tooling.

Common situations: Power loss / kill -9 during a VERSION write leaving a partial file; hand-edited or script-mangled VERSION files; very old storage dirs copied incompletely between hosts.

Related errors

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