{"record":{"id":"2d7859befaef2b40","repo":"apache/hadoop","slug":"path-already-exists-as-a-directory","errorCode":null,"errorMessage":"<path> already exists as a directory","messagePattern":"<path> already exists as a directory","errorType":"exception","errorClass":"FileAlreadyExistsException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSDirWriteFileOp.java","lineNumber":334,"sourceCode":"      // Create a temp node to findout the rack local nodes\n      clientNode = new NodeBase(rName.get(0) + NodeBase.PATH_SEPARATOR_STR\n          + clientMachine);\n    }\n    return clientNode;\n  }\n\n  static INodesInPath resolvePathForStartFile(FSDirectory dir,\n      FSPermissionChecker pc, String src, EnumSet<CreateFlag> flag,\n      boolean createParent) throws IOException {\n    INodesInPath iip = dir.resolvePath(pc, src, DirOp.CREATE);\n    if (dir.isPermissionEnabled()) {\n      dir.checkAncestorAccess(pc, iip, FsAction.WRITE);\n    }\n    INode inode = iip.getLastINode();\n    if (inode != null) {\n      // Verify that the destination does not exist as a directory already.\n      if (inode.isDirectory()) {\n        throw new FileAlreadyExistsException(iip.getPath() +\n            \" already exists as a directory\");\n      }\n      // Verifies it's indeed a file and perms allow overwrite\n      INodeFile.valueOf(inode, src);\n      if (dir.isPermissionEnabled() && flag.contains(CreateFlag.OVERWRITE)) {\n        dir.checkPathAccess(pc, iip, FsAction.WRITE);\n      }\n    } else {\n      if (!createParent) {\n        dir.verifyParentDir(iip);\n      }\n      if (!flag.contains(CreateFlag.CREATE)) {\n        throw new FileNotFoundException(\"Can't overwrite non-existent \" + src);\n      }\n    }\n    return iip;\n  }\n","sourceCodeStart":316,"sourceCodeEnd":352,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSDirWriteFileOp.java#L316-L352","documentation":"resolvePathForStartFile rejects create/overwrite when the target path already resolves to a directory: a directory can never be replaced by a file, so FileAlreadyExistsException is thrown before lease or quota work begins. This mirrors POSIX open(O_CREAT) semantics where the target must be a regular file.","triggerScenarios":"FileSystem.create(path, ...) with or without overwrite where the resolved path is an existing directory; typical with output committers or frameworks writing to a path that collides with an existing directory.","commonSituations":"MapReduce/Spark/Hive output path equal to an existing directory; path-building code that accidentally targets an input directory; leftover directory from a previous run with a different layout.","solutions":["Point the writer at a file path that does not collide (for example outputPath/part-00000), or delete/rename the existing directory first","Guard with fs.exists(path) && fs.getFileStatus(path).isDirectory() before create","If a file was intended, remove the directory (after verifying it is safe) or choose another name"],"exampleFix":"// before: path exists as a directory\ntry (FSDataOutputStream out = fs.create(dirPath)) { ... }\n\n// after: write a file inside it\nPath outFile = new Path(dirPath, \"part-00000\");\nif (fs.exists(dirPath) && fs.getFileStatus(dirPath).isDirectory()) {\n  try (FSDataOutputStream out = fs.create(outFile, true)) { ... }\n}","handlingStrategy":"validation","validationCode":"if (fs.exists(path) && fs.getFileStatus(path).isDirectory()) {\n  throw new IllegalArgumentException(\"Output path is a directory: \" + path);\n}\ntry (FSDataOutputStream out = fs.create(path, true)) { ... }","typeGuard":"static boolean isDirectoryTarget(FileSystem fs, Path p) throws IOException {\n  return fs.exists(p) && fs.getFileStatus(p).isDirectory();\n}","tryCatchPattern":"try {\n  out = fs.create(path, true);\n} catch (FileAlreadyExistsException e) {\n  // path is a directory: pick a file path inside it or rename it first\n}","preventionTips":["Lay out output paths so files never share a name with directories","Delete or rename stale output directories before reruns","Guard every overwrite with an exists()+isDirectory() check"],"tags":["hdfs","create","path-conflict","directory"],"backgroundTag":"path-already-exists","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}