{"record":{"id":"4de84387c6082298","repo":"apache/hadoop","slug":"destination-parentfile-directory-cannot-be-cre","errorCode":null,"errorMessage":"Destination '{parentFile}' directory cannot be created","messagePattern":"Destination '(.+?)' directory cannot be created","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":1345,"sourceCode":"      throw new NullPointerException(\"Source must not be null\");\n    }\n    if (destFile == null) {\n      throw new NullPointerException(\"Destination must not be null\");\n    }\n    if (srcFile.exists() == false) {\n      throw new FileNotFoundException(\"Source '\" + srcFile + \"' does not exist\");\n    }\n    if (srcFile.isDirectory()) {\n      throw new IOException(\"Source '\" + srcFile + \"' exists but is a directory\");\n    }\n    if (srcFile.getCanonicalPath().equals(destFile.getCanonicalPath())) {\n      throw new IOException(\"Source '\" + srcFile + \"' and destination '\" +\n          destFile + \"' are the same\");\n    }\n    File parentFile = destFile.getParentFile();\n    if (parentFile != null) {\n      if (!parentFile.mkdirs() && !parentFile.isDirectory()) {\n        throw new IOException(\"Destination '\" + parentFile\n            + \"' directory cannot be created\");\n      }\n    }\n    if (destFile.exists()) {\n      if (FileUtil.canWrite(destFile) == false) {\n        throw new IOException(\"Destination '\" + destFile\n            + \"' exists but is read-only\");\n      } else {\n        if (destFile.delete() == false) {\n          throw new IOException(\"Destination '\" + destFile\n              + \"' exists but cannot be deleted\");\n        }\n      }\n    }\n    try {\n      NativeIO.copyFileUnbuffered(srcFile, destFile);\n    } catch (NativeIOException e) {\n      throw new IOException(\"Failed to copy \" + srcFile.getCanonicalPath()","sourceCodeStart":1327,"sourceCodeEnd":1363,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/common/Storage.java#L1327-L1363","documentation":"Guard clause of Storage.nativeCopyFileUnbuffered: destFile.getParentFile() could neither be created (mkdirs() false) nor already existed as a directory, so the copy aborts before writing. This means the destination parent path is unusable - shadowed by a regular file, unwritable, or on a read-only mount.","triggerScenarios":"A regular file occupies a path component of the destination directory (e.g. /data/x is a file, dest is /data/x/y); the daemon user lacks write permission on the grandparent; the volume is mounted read-only; NFS export denies directory creation.","commonSituations":"Manually created placeholder files where directories were expected; storage dirs prepared by root with wrong ownership; read-only recovery mounts; container images with conflicting paths.","solutions":["Check whether a regular file shadows the parent path: ls -l <parent> and remove or relocate it","Create the directory yourself as the daemon user, or chown/chmod it so mkdirs can succeed","Confirm the volume is mounted read-write"],"exampleFix":"// before\nStorage.nativeCopyFileUnbuffered(src, new File(\"/data/x/y/fsimage\"), true); // /data/x is a file\n// after\nFiles.createDirectories(new File(\"/data/x/y\").toPath());\nStorage.nativeCopyFileUnbuffered(src, new File(\"/data/x/y/fsimage\"), true);","handlingStrategy":"validation","validationCode":"File parent = destFile.getParentFile();\nif (parent != null) {\n  if (parent.exists() && !parent.isDirectory())\n    throw new IOException(\"path shadowed by a file: \" + parent);\n  Files.createDirectories(parent.toPath());\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pre-create destination directories as part of setup instead of relying on the library's mkdirs","Alert when mkdirs fails - it almost always means a permissions or shadowing problem","Keep storage-dir ownership consistent with the daemon user"],"tags":["hdfs","file-copy","mkdir","permissions","filesystem"],"backgroundTag":"mkdir-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}