{"record":{"id":"b762acecd865511c","repo":"apache/hadoop","slug":"failed-to-rename-since-the-dest-path-s-already-ex","errorCode":null,"errorMessage":"Failed to rename since the dest path %s already exists.","messagePattern":"Failed to rename since the dest path (.+?) already exists\\.","errorType":"exception","errorClass":"FileAlreadyExistsException","httpStatus":null,"severity":"error","filePath":"hadoop-cloud-storage-project/hadoop-tos/src/main/java/org/apache/hadoop/fs/tosfs/RawFileSystem.java","lineNumber":316,"sourceCode":"\n    // 2. No need to check the dest path because renaming itself is allowed.\n    if (src.equals(finalDstPath)) {\n      return finalDstPath;\n    }\n\n    // 3. Ensure the source path cannot be the ancestor of destination path.\n    if (RawFSUtils.inSubtree(src, finalDstPath)) {\n      throw new IOException(String.format(\"Failed to rename since it is prohibited to \" +\n          \"rename dest path %s under src path %s\", finalDstPath, src));\n    }\n\n    // 4. Ensure the destination path doesn't exist.\n    FileStatus finalDstStatus = destStatus;\n    if (destStatus != null && destStatus.isDirectory()) {\n      finalDstStatus = getFileStatusOrNull(finalDstPath);\n    }\n    if (finalDstStatus != null) {\n      throw new FileAlreadyExistsException(\n          String.format(\"Failed to rename since the dest path %s already exists.\", finalDstPath));\n    } else {\n      return finalDstPath;\n    }\n  }\n\n  private FileStatus checkAndGetSrcStatus(Path src) throws IOException {\n    // throw FileNotFoundException if src not found.\n    FileStatus srcStatus = innerFileStatus(src);\n\n    if (src.isRoot()) {\n      throw new IOException(String.format(\"Cannot rename the root directory %s to another name\",\n          src));\n    }\n    return srcStatus;\n  }\n\n  @Override","sourceCodeStart":298,"sourceCodeEnd":334,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-cloud-storage-project/hadoop-tos/src/main/java/org/apache/hadoop/fs/tosfs/RawFileSystem.java#L298-L334","documentation":"rename() in RawFileSystem throws FileAlreadyExistsException when the final destination already exists. Hadoop's atomic-rename contract forbids overwriting: if dest is a file, or dest is a directory and dest/srcName already exists, the rename is rejected.","triggerScenarios":"rename(src, dst) where dst exists as a file; or dst exists as a directory and new Path(dst, src.getName()) already exists (the 'rename into directory' adjustment), as detected via getFileStatusOrNull(finalDstPath).","commonSituations":"Idempotent job re-runs that 'move' results into a directory already populated by a previous run; merge scripts that collapse two trees into one; leftover destination objects from an aborted attempt.","solutions":["Delete or move the colliding destination object first (fs.delete(finalDst, false)) when overwrite semantics are acceptable","Guard the rename: if (!fs.exists(finalDst)) fs.rename(src, dst), else pick a unique destination name","Clean the destination directory between runs instead of reusing it"],"exampleFix":"// before\nfs.rename(src, dstDir); // dstDir/srcName already exists -> FileAlreadyExistsException\n\n// after\nPath finalDst = fs.getFileStatus(dstDir).isDirectory()\n    ? new Path(dstDir, src.getName()) : dstDir;\nif (fs.exists(finalDst)) { fs.delete(finalDst, false); }\nfs.rename(src, dstDir);","handlingStrategy":"validation","validationCode":"Path finalDst = fs.exists(dst) && fs.getFileStatus(dst).isDirectory()\n    ? new Path(dst, src.getName()) : dst;\nif (fs.exists(finalDst)) {\n  fs.delete(finalDst, false); // or choose a unique name\n}\nboolean renamed = fs.rename(src, dst);","typeGuard":null,"tryCatchPattern":"try { fs.rename(src, dst); }\ncatch (FileAlreadyExistsException e) {\n  // destination collision: delete/rename target and retry once\n}","preventionTips":["Treat tos:// rename as move-not-overwrite: pre-clear the destination","Clean destination dirs between job runs","Log the final destination (after the dir adjustment) when diagnosing collisions"],"tags":["rename","file-already-exists","destination-conflict","tos"],"backgroundTag":"rename-destination-exists","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}