{"record":{"id":"8c0df27eb0623f6d","repo":"apache/hadoop","slug":"cannot-create-directory-rootpath","errorCode":null,"errorMessage":"Cannot create directory {rootPath}","messagePattern":"Cannot create directory (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/common/Storage.java","lineNumber":681,"sourceCode":"          location.getStorageType() == StorageType.PROVIDED) {\n        // currently we assume that PROVIDED storages are always NORMAL\n        return StorageState.NORMAL;\n      }\n\n      assert root != null : \"root is null\";\n      boolean hadMkdirs = false;\n      String rootPath = root.getCanonicalPath();\n      try { // check that storage exists\n        if (!root.exists()) {\n          // storage directory does not exist\n          if (startOpt != StartupOption.FORMAT &&\n              startOpt != StartupOption.HOTSWAP) {\n            LOG.warn(\"Storage directory {} does not exist\", rootPath);\n            return StorageState.NON_EXISTENT;\n          }\n          LOG.info(\"{} does not exist. Creating ...\", rootPath);\n          if (!root.mkdirs()) {\n            throw new IOException(\"Cannot create directory \" + rootPath);\n          }\n          hadMkdirs = true;\n        }\n        // or is inaccessible\n        if (!root.isDirectory()) {\n          LOG.warn(\"{} is not a directory\", rootPath);\n          return StorageState.NON_EXISTENT;\n        }\n        if (!FileUtil.canWrite(root)) {\n          LOG.warn(\"Cannot access storage directory {}\", rootPath);\n          return StorageState.NON_EXISTENT;\n        }\n      } catch(SecurityException ex) {\n        LOG.warn(\"Cannot access storage directory {}\", rootPath, ex);\n        return StorageState.NON_EXISTENT;\n      }\n\n      this.lock(); // lock storage if it exists","sourceCodeStart":663,"sourceCodeEnd":699,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/common/Storage.java#L663-L699","documentation":"In Storage.analyzeStorage, when the storage root does not exist and startOpt is FORMAT or HOTSWAP, the code creates it with root.mkdirs(); failure throws IOException('Cannot create directory <rootPath>'). This is the top-level storage root (e.g. /dfs/nn), created before any locking or layout work, so failures are purely filesystem-level.","triggerScenarios":"Formatting into a new path whose parent is not writable by the daemon user, where a component of the path exists as a regular file, on a read-only filesystem, or with no free space/inodes.","commonSituations":"dfs.namenode.name.dir pointing at a fresh mount whose parent is root-owned; typo'd path colliding with an existing file; read-only mount; exhausted inodes.","solutions":["Pre-create the parent path with correct ownership: mkdir -p <parent> && chown <hdfs-user> <parent>","Fix or correct the configured path (dfs.namenode.name.dir / dfs.datanode.data.dir) if it collides with a file","Verify the mount is read-write and has space and inodes (df -h, df -i), then retry"],"exampleFix":"# before\nsudo -u hdfs hdfs namenode -format   # /dfs/nn parent root-owned\n\n# after\nsudo mkdir -p /dfs && sudo chown hdfs:hdfs /dfs\nsudo -u hdfs hdfs namenode -format","handlingStrategy":"validation","validationCode":"Path root = Paths.get(conf.get(DFSConfigKeys.DFS_NAMENODE_NAME_DIR_KEY));\nPath parent = root.getParent();\nif (Files.exists(root) && !Files.isDirectory(root)) throw new IOException(root + \" is a file\");\nif (!Files.isWritable(Files.exists(parent) ? parent : parent.getParent())) {\n  throw new IOException(\"No write permission to create \" + root);\n}\n// then run format","typeGuard":null,"tryCatchPattern":"try {\n  sd.analyzeStorage(startOpt, storage, false);\n} catch (IOException e) {\n  if (e.getMessage().startsWith(\"Cannot create directory\")) {\n    throw new IOException(\"Create parent of \" + rootPath + \" with correct ownership first\", e);\n  } else throw e;\n}","preventionTips":["Pre-create storage roots with the daemon user as owner during host provisioning","Validate configured storage paths in config-lint checks (no file collisions, writable parents)","Check df/inodes before first format on new mounts"],"tags":["hdfs","storage","format","permissions","mkdir","config"],"backgroundTag":"cannot-create-directory","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}