{"record":{"id":"74f14fa9f2d49c82","repo":"apache/hadoop","slug":"file-s-already-exists","errorCode":null,"errorMessage":"File: %s already exists","messagePattern":"File: (.+?) already exists","errorType":"exception","errorClass":"FileAlreadyExistsException","httpStatus":null,"severity":"error","filePath":"hadoop-cloud-storage-project/hadoop-cos/src/main/java/org/apache/hadoop/fs/cosn/CosNFileSystem.java","lineNumber":651,"sourceCode":"          dstParentPath);\n    }\n\n    if (null != dstParentPath) {\n      LOG.debug(\"It is not allowed to rename a parent directory:[{}] \"\n          + \"to its subdirectory:[{}].\", src, dst);\n      throw new IOException(String.format(\n          \"It is not allowed to rename a parent directory: %s \"\n              + \"to its subdirectory: %s\", src, dst));\n    }\n\n    FileStatus dstFileStatus;\n    try {\n      dstFileStatus = this.getFileStatus(dst);\n\n      // The destination path exists and is a file,\n      // and the rename operation is not allowed.\n      if (dstFileStatus.isFile()) {\n        throw new FileAlreadyExistsException(String.format(\n            \"File: %s already exists\", dstFileStatus.getPath()));\n      } else {\n        // The destination path is an existing directory,\n        // and it is checked whether there is a file or directory\n        // with the same name as the source path under the destination path\n        dst = new Path(dst, src.getName());\n        FileStatus[] statuses;\n        try {\n          statuses = this.listStatus(dst);\n        } catch (FileNotFoundException e) {\n          statuses = null;\n        }\n        if (null != statuses && statuses.length > 0) {\n          LOG.debug(\"Cannot rename source file: [{}] to dest file: [{}], \"\n              + \"because the file already exists.\", src, dst);\n          throw new FileAlreadyExistsException(\n              String.format(\n                  \"File: %s already exists\", dst","sourceCodeStart":633,"sourceCodeEnd":669,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-cloud-storage-project/hadoop-cos/src/main/java/org/apache/hadoop/fs/cosn/CosNFileSystem.java#L633-L669","documentation":"When a rename destination exists and is a FILE, CosN throws FileAlreadyExistsException('File: <dst> already exists') rather than silently overwriting. Rename in CosN is implemented as copy+delete, which cannot atomically replace an object, so destination collisions are rejected outright. Note the classic Hadoop contract permits returning false here; CosN chooses to fail fast instead.","triggerScenarios":"fs.rename(src, dst) where dst resolves to an existing file; hadoop fs -mv onto an existing file name; idempotent retry of a rename step after a partial failure where dst was already committed but src was recreated.","commonSituations":"Job-step retries after partial failure; two writers racing to promote the same final name; habits carried over from local fs -mv where the destination is replaced.","solutions":["If overwrite is intended: fs.delete(dst, false) first, then rename (accepting the small non-atomic window).","Write to temporary names and only rename to a final name you have verified is absent.","Make the step idempotent: treat 'dst already exists with matching content/length' as success and skip."],"exampleFix":"// before\nfs.rename(tmpPath, finalPath); // FileAlreadyExistsException: File: ... already exists\n\n// after\nif (fs.exists(finalPath)) {\n  if (fs.getFileStatus(finalPath).getLen() != fs.getFileStatus(tmpPath).getLen()) {\n    fs.delete(finalPath, false);\n    fs.rename(tmpPath, finalPath);\n  } // else: already committed, skip\n} else {\n  fs.rename(tmpPath, finalPath);\n}","handlingStrategy":"validation","validationCode":"if (fs.exists(dst) && fs.getFileStatus(dst).isFile()) {\n  if (!allowOverwrite) { throw new IllegalStateException('Destination exists: ' + dst); }\n  fs.delete(dst, false);\n}\nfs.rename(src, dst);","typeGuard":"static boolean isRenameCollision(Throwable t) {\n  return t instanceof FileAlreadyExistsException;\n}","tryCatchPattern":"try {\n  fs.rename(src, dst);\n} catch (FileAlreadyExistsException e) {\n  // idempotent retry semantics: same length means already committed\n  if (fs.getFileStatus(dst).getLen() == expectedLen) { /* done */ } else { throw e; }\n}","preventionTips":["Write to temp names and rename to final names you verified absent","Make rename steps idempotent across retries","Do not assume object-store rename overwrites like local mv"],"tags":["cosn","hadoop","rename","destination-exists","file-already-exists"],"backgroundTag":"rename-destination-exists","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}