{"record":{"id":"ab31e426fb7652e0","repo":"apache/hadoop","slug":"namenode-directory-sd-getroot-is-not-for","errorCode":null,"errorMessage":"NameNode directory \" + sd.getRoot() + \" is not formatted.","messagePattern":"NameNode directory \" \\+ sd\\.getRoot\\(\\) \\+ \" is not formatted\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NNStorage.java","lineNumber":666,"sourceCode":"   * which is checked every time the datanode is communicating with the\n   * namenode. Datanodes that do not 'know' the namespaceID are rejected.\n   *\n   * @return new namespaceID\n   */\n  private static int newNamespaceID() {\n    int newID = 0;\n    while(newID == 0) {\n      newID = ThreadLocalRandom.current().nextInt(0x7FFFFFFF);  // use 31 bits\n    }\n    return newID;\n  }\n\n  @Override // Storage\n  protected void setFieldsFromProperties(\n      Properties props, StorageDirectory sd) throws IOException {\n    super.setFieldsFromProperties(props, sd);\n    if (layoutVersion == 0) {\n      throw new IOException(\"NameNode directory \"\n                            + sd.getRoot() + \" is not formatted.\");\n    }\n\n    // Set Block pool ID in version with federation support\n    if (NameNodeLayoutVersion.supports(\n        LayoutVersion.Feature.FEDERATION, getLayoutVersion())) {\n      String sbpid = props.getProperty(\"blockpoolID\");\n      setBlockPoolID(sd.getRoot(), sbpid);\n    }\n    setDeprecatedPropertiesForUpgrade(props);\n  }\n\n  void readProperties(StorageDirectory sd, StartupOption startupOption)\n      throws IOException {\n    Properties props = readPropertiesFile(sd.getVersionFile());\n    if (props == null) {\n      throw new IOException(\n          \"Properties not found  for storage directory \" + sd);","sourceCodeStart":648,"sourceCodeEnd":684,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NNStorage.java#L648-L684","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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.","Verify mounts ('df <dir>') before restart - an unmounted disk looks exactly like an unformatted one."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Pre-start check: every name dir must carry a formatted VERSION\nfor (String loc : conf.getTrimmedStrings(\"dfs.namenode.name.dir\")) {\n  Path version = Paths.get(URI.create(loc.startsWith(\"/\") ? \"file://\" + loc : loc))\n      .resolve(\"current\").resolve(\"VERSION\");\n  boolean formatted = Files.isRegularFile(version);\n  if (!formatted) {\n    throw new IllegalStateException(\"Not formatted, refusing NN start: \" + version);\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run 'hdfs namenode -format' exactly once per fresh cluster, as the hdfs user, with mounts verified.","Add a pre-start systemd/exec check that VERSION exists in every configured dir.","Treat format as a destructive action gated by change management - never script it blindly."],"tags":["hdfs","namenode","format","storage","version-file"],"backgroundTag":"namenode-not-formatted","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}