What causes "Properties not found for storage directory " + sd" in apache/hadoop?

Inspect the directory named in the message: ls -l /VERSION and df - often it is simply an unmounted volume.

apache/hadoop · critical · IOException

Properties not found for storage directory " + sd

Error message

Properties not found  for storage directory " + sd

What it means

readProperties loads a storage directory's VERSION via readPropertiesFile; a null return (file absent or unopenable) yields 'Properties not found for storage directory sd'. Unlike the layoutVersion==0 'not formatted' case, this fires when the VERSION file itself is missing or unreadable for that directory - presence of the file, not its content, is the problem.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NNStorage.java:683

    if (layoutVersion == 0) {
      throw new IOException("NameNode directory "
                            + sd.getRoot() + " is not formatted.");
    }

    // Set Block pool ID in version with federation support
    if (NameNodeLayoutVersion.supports(
        LayoutVersion.Feature.FEDERATION, getLayoutVersion())) {
      String sbpid = props.getProperty("blockpoolID");
      setBlockPoolID(sd.getRoot(), sbpid);
    }
    setDeprecatedPropertiesForUpgrade(props);
  }

  void readProperties(StorageDirectory sd, StartupOption startupOption)
      throws IOException {
    Properties props = readPropertiesFile(sd.getVersionFile());
    if (props == null) {
      throw new IOException(
          "Properties not found  for storage directory " + sd);
    }
    if (HdfsServerConstants.RollingUpgradeStartupOption.ROLLBACK
        .matches(startupOption)) {
      int lv = Integer.parseInt(getProperty(props, sd, "layoutVersion"));
      if (lv > getServiceLayoutVersion()) {
        // we should not use a newer version for rollingUpgrade rollback
        throw new IncorrectVersionException(getServiceLayoutVersion(), lv,
            "storage directory " + sd.getRoot().getAbsolutePath());
      }
      props.setProperty("layoutVersion",
          Integer.toString(getServiceLayoutVersion()));
    }
    setFieldsFromProperties(props, sd);
  }

  /**
   * Pull any properties out of the VERSION file that are from older

View on GitHub (pinned to 2add963021)

Solutions

Inspect the directory named in the message: ls -l <root>/VERSION and df <root> - often it is simply an unmounted volume.
Restore VERSION (with consistent fsimage/edits) from a healthy sibling dir or backup; every ID field must match the other directories.
If the cluster is brand new, just format properly rather than hand-crafting VERSION.

Defensive patterns

Strategy: validation

Validate before calling

// Pre-start check: VERSION must exist and be readable in every dir
for (String loc : conf.getTrimmedStrings("dfs.namenode.name.dir")) {
  Path v = Paths.get(stripScheme(loc)).resolve("current").resolve("VERSION");
  if (!Files.isReadable(v)) {
    throw new IllegalStateException("VERSION missing/unreadable - check mount and permissions: " + v);
  }
}

Prevention

Verify mounts before NN start (df per dir) - unmounted volumes look like missing VERSION.
Keep VERSION in backup snapshots; restoring image without VERSION just moves the failure.
Restrict cleanup tooling from touching name dirs.

When it happens

Trigger: VERSION deleted, the directory unmounted or mounted read-only, permissions denying read, or a partial restore that skipped VERSION - hit while the NN starts, or during rollback/recovery reads of a storage dir.

Common situations: Storage unmounted at boot so NN sees an empty mountpoint; cleanup scripts removing files in the name dir; one failed disk among several name dirs; restore from backup that copied image/edits but not VERSION.

Related errors

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