{"record":{"id":"8fe73eaa0d075ded","repo":"apache/hadoop","slug":"failed-to-promote-tmp-file-tmptarget-to-target","errorCode":null,"errorMessage":"Failed to promote tmp-file:{tmpTarget} to: {target}","messagePattern":"Failed to promote tmp-file:(.+?) to: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-tools/hadoop-distcp/src/main/java/org/apache/hadoop/tools/mapred/RetriableFileCopyCommand.java","lineNumber":259,"sourceCode":"      }\n      outStream = new BufferedOutputStream(out);\n    } else {\n      outStream = new BufferedOutputStream(targetFS.append(targetPath,\n          copyBufferSize));\n    }\n    return copyBytes(source, sourceOffset, outStream, copyBufferSize,\n        context);\n  }\n\n  //If target file exists and unable to delete target - fail\n  //If target doesn't exist and unable to create parent folder - fail\n  //If target is successfully deleted and parent exists, if rename fails - fail\n  private void promoteTmpToTarget(Path tmpTarget, Path target, FileSystem fs)\n                                  throws IOException {\n    if ((fs.exists(target) && !fs.delete(target, false))\n        || (!fs.exists(target.getParent()) && !fs.mkdirs(target.getParent()))\n        || !fs.rename(tmpTarget, target)) {\n      throw new IOException(\"Failed to promote tmp-file:\" + tmpTarget\n                              + \" to: \" + target);\n    }\n  }\n\n  private Path getTempFile(Path target, Mapper.Context context) {\n    Path targetWorkPath = new Path(context.getConfiguration().\n        get(DistCpConstants.CONF_LABEL_TARGET_WORK_PATH));\n\n    Path root = target.equals(targetWorkPath) ? targetWorkPath.getParent()\n        : targetWorkPath;\n    Path tempFile = new Path(root, \".distcp.tmp.\" +\n        context.getTaskAttemptID().toString() +\n        \".\" + String.valueOf(System.currentTimeMillis()));\n    LOG.info(\"Creating temp file: {}\", tempFile);\n    return tempFile;\n  }\n\n  @VisibleForTesting","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-distcp/src/main/java/org/apache/hadoop/tools/mapred/RetriableFileCopyCommand.java#L241-L277","documentation":"RetriableFileCopyCommand writes each file to a temp file (.distcp.tmp.<taskAttemptId> under the work path) and then promotes it via promoteTmpToTarget(). The promote fails if the target exists and delete(target, false) fails, if the target's parent is missing and mkdirs fails, or if the final rename fails. The copied bytes remain in the tmp file named in the message.","triggerScenarios":"An existing target file cannot be deleted (held open by another writer, permission denied); the target's parent directory was removed while the copy ran; permission loss on the target dir; the tmp file cleaned up before promotion; -append pointing at a file being appended elsewhere.","commonSituations":"Concurrent distcp jobs or other writers targeting the same file; aggressive tmp-file cleanup jobs; target ACLs changed mid-job; multiple jobs sharing one destination directory.","solutions":["Remove or stop whatever conflicts on the target file, delete the stale target file, and re-run with -update","Ensure the target's parent directory exists and is writable by the job user","Whitelist .distcp.tmp.* files from cleanup processes while distcp runs","If repeating the copy is expensive, recover the bytes from the named tmp file"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// ensure exclusive ownership of the destination before the run\nif (targetFS.exists(targetFile)) {\n  if (!targetFS.delete(targetFile, false)) {\n    throw new IOException(\"cannot clear target for exclusive write: \" + targetFile);\n  }\n}","typeGuard":null,"tryCatchPattern":"catch (IOException e) {  // 'Failed to promote tmp-file:... to:...'\n  // tmp file named in the message holds the copied bytes; clear the conflict and re-run -update\n}","preventionTips":["One writer per target file; never overlap distcp jobs on one destination","Protect .distcp.tmp.* files from cleanup processes during jobs","Avoid -append onto files that other processes append to","Verify delete permission on pre-existing target files before starting"],"tags":["distcp","hadoop","rename","tmp-file","concurrency"],"backgroundTag":"rename-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}