{"record":{"id":"2fe64a97583c927e","repo":"apache/hadoop","slug":"mkdirs-failed-to-create-dir","errorCode":null,"errorMessage":"Mkdirs failed to create ${dir}","messagePattern":"Mkdirs failed to create (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/FileIoProvider.java","lineNumber":697,"sourceCode":"   * @param volume  target volume. null if unavailable.\n   * @param dir  directory to be created.\n   * @throws IOException  if the directory could not created\n   */\n  public void mkdirsWithExistsCheck(\n      @Nullable FsVolumeSpi volume, File dir) throws IOException {\n    final long begin = profilingEventHook.beforeMetadataOp(volume, MKDIRS);\n    boolean succeeded = false;\n    try {\n      faultInjectorEventHook.beforeMetadataOp(volume, MKDIRS);\n      succeeded = dir.isDirectory() || dir.mkdirs();\n      profilingEventHook.afterMetadataOp(volume, MKDIRS, begin);\n    } catch(Exception e) {\n      onFailure(volume, begin);\n      throw e;\n    }\n\n    if (!succeeded) {\n      throw new IOException(\"Mkdirs failed to create \" + dir);\n    }\n  }\n\n  /**\n   * Get a listing of the given directory using\n   * {@link FileUtil#listFiles(File)}.\n   *\n   * @param volume  target volume. null if unavailable.\n   * @param dir  Directory to be listed.\n   * @return  array of file objects representing the directory entries.\n   * @throws IOException\n   */\n  public File[] listFiles(\n      @Nullable FsVolumeSpi volume, File dir) throws IOException {\n    final long begin = profilingEventHook.beforeMetadataOp(volume, LIST);\n    try {\n      faultInjectorEventHook.beforeMetadataOp(volume, LIST);\n      File[] children = FileUtil.listFiles(dir);","sourceCodeStart":679,"sourceCodeEnd":715,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/datanode/FileIoProvider.java#L679-L715","documentation":"The exists-or-create variant in FileIoProvider: it computes succeeded = dir.isDirectory() || dir.mkdirs(), and throws IOException('Mkdirs failed to create ' + dir) when both fail. Same failure surface as the plain mkdirs wrapper — the path is not a directory and could not be created — used by callers that only need the directory to exist.","triggerScenarios":"Calling this ensure-directory-exists helper when the path is occupied by a regular file, a parent is missing or not writable by the DataNode user, the volume is full (blocks or inodes), or the storage backing the volume (NFS/fuse) rejects the mkdir.","commonSituations":"DataNode data-dir permission drift after a user change or restore; inode exhaustion on small local filesystems; leftover files at directory paths after an interrupted operation; degraded NFS mounts.","solutions":["Verify the path is not occupied by a plain file and remove the conflict if it is.","Fix parent ownership/permissions for the DataNode user (chown/chmod on the data-dir tree).","Check `df -h` and `df -i` on the volume; free space or inodes.","Validate the mount health if the volume is network-backed."],"exampleFix":"// before\nfileIoProvider.mkdirsWithExistsCheck(volume, dir);\n\n// after: distinguish 'already a dir' from 'occupied by a file' up front\nif (!dir.isDirectory() && dir.exists()) {\n  throw new IOException(\"cannot create directory, path is a file: \" + dir);\n}\nfileIoProvider.mkdirsWithExistsCheck(volume, dir);","handlingStrategy":"validation","validationCode":"if (!dir.isDirectory() && dir.exists()) {\n  // path is occupied by a non-directory: resolve the conflict first\n}\nif (dir.getParentFile() != null && !dir.getParentFile().canWrite()) {\n  // parent not writable by the DataNode user: fix permissions\n}","typeGuard":null,"tryCatchPattern":"try {\n  fileIoProvider.mkdirsWithExistsCheck(volume, dir);\n} catch (IOException e) {\n  // dir named in the message: check path conflicts, perms, and volume space/inodes\n}","preventionTips":["Validate directory paths are free of file conflicts before starting the DataNode","Watch df -h and df -i on volumes that receive many new directories","Audit data-dir permissions after user or restore changes"],"tags":["filesystem","mkdirs","permissions","disk-full","hdfs","datanode"],"backgroundTag":"mkdir-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}