{"record":{"id":"7b36ee7671d69259","repo":"apache/hadoop","slug":"namenode-is-not-formatted","errorCode":null,"errorMessage":"NameNode is not formatted.","messagePattern":"NameNode is not formatted\\.","errorType":"exception","errorClass":"java.io.IOException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImage.java","lineNumber":254,"sourceCode":"                             && startOpt != StartupOption.IMPORT)  \n      throw new IOException(\n          \"All specified directories are not accessible or do not exist.\");\n    \n    // 1. For each data directory calculate its state and \n    // check whether all is consistent before transitioning.\n    Map<StorageDirectory, StorageState> dataDirStates = \n             new HashMap<StorageDirectory, StorageState>();\n    boolean isFormatted = recoverStorageDirs(startOpt, storage, dataDirStates);\n\n    if (LOG.isTraceEnabled()) {\n      LOG.trace(\"Data dir states:\\n  \" +\n        Joiner.on(\"\\n  \").withKeyValueSeparator(\": \")\n        .join(dataDirStates));\n    }\n    \n    if (!isFormatted && startOpt != StartupOption.ROLLBACK \n                     && startOpt != StartupOption.IMPORT) {\n      throw new IOException(\"NameNode is not formatted.\");      \n    }\n\n\n    int layoutVersion = storage.getLayoutVersion();\n    if (startOpt == StartupOption.METADATAVERSION) {\n      System.out.println(\"HDFS Image Version: \" + layoutVersion);\n      System.out.println(\"Software format version: \" +\n          storage.getServiceLayoutVersion());\n      return false;\n    }\n\n    if (layoutVersion < Storage.LAST_PRE_UPGRADE_LAYOUT_VERSION) {\n      NNStorage.checkVersionUpgradable(storage.getLayoutVersion());\n    }\n    if (startOpt != StartupOption.UPGRADE\n        && startOpt != StartupOption.UPGRADEONLY\n        && !RollingUpgradeStartupOption.STARTED.matches(startOpt)\n        && layoutVersion < Storage.LAST_PRE_UPGRADE_LAYOUT_VERSION","sourceCodeStart":236,"sourceCodeEnd":272,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSImage.java#L236-L272","documentation":"FSImage.recoverStorageDirs() visited every storage directory and none contained formatted state (a VERSION file), so isFormatted stayed false. With a normal startup option the NameNode has no namespace to load and aborts. Rollback and IMPORT are exempt because they write state instead of only reading it.","triggerScenarios":"First start of a NameNode without running 'hdfs namenode -format'; dfs.namenode.name.dir retargeted to a fresh path or a wiped volume; VERSION files deleted by cleanup scripts; container started without its metadata volume mounted.","commonSituations":"Brand-new clusters never formatted; default /tmp-based name dirs cleaned on reboot; volume remounted empty after disk replacement; name.dir pointing to the wrong path after config drift.","solutions":["New cluster: run 'hdfs namenode -format [-clusterid mycluster]' then start the NameNode (never format over an existing cluster's data).","Existing cluster: check mounts and dfs.namenode.name.dir — the formatted volume is probably elsewhere or unmounted; <dir>/current/VERSION should exist.","HA cluster: copy current/ (fsimage, edits, VERSION) from the healthy Standby NameNode into this node's name dir.","Otherwise restore fsimage+edits from the Secondary NameNode checkpoint or backups."],"exampleFix":"# before\nhdfs --daemon start namenode   # IOException: NameNode is not formatted.\n\n# after (new cluster only!)\nhdfs namenode -format -clusterid mycluster\nhdfs --daemon start namenode","handlingStrategy":"validation","validationCode":"for (URI u : nameDirUris) {\n  Path versionFile = Paths.get(u.getPath(), \"VERSION\");\n  if (!Files.exists(versionFile)) {\n    // unformatted dir: format explicitly or restore metadata before starting\n  }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep NameNode metadata off /tmp (the default location is only for tests).","Script a startup check that <name.dir>/current/VERSION exists on every dir.","In HA, keep a Standby so metadata always has a second copy."],"tags":["hdfs","namenode","format","startup","storage-directory"],"backgroundTag":"namenode-not-formatted","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}