apache/hadoop · critical · IOException

NameNode directory " + sd.getRoot() + " is not formatted.

Error message

NameNode directory " + sd.getRoot() + " is not formatted.

What it means

setFieldsFromProperties runs after loading a storage directory's VERSION file; layoutVersion == 0 means the property was never present, i.e. the directory was not formatted (or its VERSION was truncated to empty). The NameNode refuses to use such a directory at startup because the on-disk format is unknown. This is the classic 'directory not formatted' signal.

Source

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

   * which is checked every time the datanode is communicating with the
   * namenode. Datanodes that do not 'know' the namespaceID are rejected.
   *
   * @return new namespaceID
   */
  private static int newNamespaceID() {
    int newID = 0;
    while(newID == 0) {
      newID = ThreadLocalRandom.current().nextInt(0x7FFFFFFF);  // use 31 bits
    }
    return newID;
  }

  @Override // Storage
  protected void setFieldsFromProperties(
      Properties props, StorageDirectory sd) throws IOException {
    super.setFieldsFromProperties(props, sd);
    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);

View on GitHub (pinned to 2add963021)

Solutions

1. New cluster: run 'hdfs namenode -format' (with -clusterId if part of an HA/federated setup) exactly once, as the right user, and confirm every configured name.dir receives VERSION.
2. Existing cluster where one dir is bad: restore that dir from backup or a healthy sibling copy so IDs and image/edits match the others.
3. Verify mounts ('df <dir>') before restart - an unmounted disk looks exactly like an unformatted one.

// Pre-start check: every name dir must carry a formatted VERSION
for (String loc : conf.getTrimmedStrings("dfs.namenode.name.dir")) {
  Path version = Paths.get(URI.create(loc.startsWith("/") ? "file://" + loc : loc))
      .resolve("current").resolve("VERSION");
  boolean formatted = Files.isRegularFile(version);
  if (!formatted) {
    throw new IllegalStateException("Not formatted, refusing NN start: " + version);
  }
}

When it happens

Trigger: Starting the NameNode against a dfs.namenode.name.dir entry that has no VERSION or a zero-byte/corrupted VERSION: fresh disks where format was skipped or interrupted, a not-yet-mounted volume, or a partially wiped directory.

Common situations: New cluster where 'hdfs namenode -format' was skipped or ran as a different user writing elsewhere; mount not mounted at boot so the NN sees an empty dir; only some of multiple name.dirs got formatted.

Related errors

• Can't format the storage directory because the current direc
• Properties not found for storage directory " + sd
• file VERSION has no block pool Id.
• No storage directories contained VERSION information
• All the storage failed while writing properties to VERSION f

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