{"record":{"id":"4f03c8ca7fa91f5b","repo":"apache/hadoop","slug":"renameto-src-src-dst-dst-failed","errorCode":null,"errorMessage":"renameTo(src=${src}, dst=${dst}) failed.","messagePattern":"renameTo\\(src=(.+?), dst=(.+?)\\) failed\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/nativeio/NativeIO.java","lineNumber":1068,"sourceCode":"      LOG.info(\"Initialized cache for UID to User mapping with a cache\" +\n          \" timeout of \" + cacheTimeout/1000 + \" seconds.\");\n      initialized = true;\n    }\n  }\n  \n  /**\n   * A version of renameTo that throws a descriptive exception when it fails.\n   *\n   * @param src                  The source path\n   * @param dst                  The destination path\n   * \n   * @throws NativeIOException   On failure.\n   */\n  public static void renameTo(File src, File dst)\n      throws IOException {\n    if (!nativeLoaded) {\n      if (!src.renameTo(dst)) {\n        throw new IOException(\"renameTo(src=\" + src + \", dst=\" +\n          dst + \") failed.\");\n      }\n    } else {\n      renameTo0(src.getAbsolutePath(), dst.getAbsolutePath());\n    }\n  }\n\n  /**\n   * Creates a hardlink \"dst\" that points to \"src\".\n   *\n   * This is deprecated since JDK7 NIO can create hardlinks via the\n   * {@link java.nio.file.Files} API.\n   *\n   * @param src source file\n   * @param dst hardlink location\n   * @throws IOException raised on errors performing I/O.\n   */\n  @Deprecated","sourceCodeStart":1050,"sourceCodeEnd":1086,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/nativeio/NativeIO.java#L1050-L1086","documentation":"NativeIO.renameTo's Java fallback: when the native library is not loaded, it uses File.renameTo(), which reports only boolean success. On failure it throws IOException(\"renameTo(src=..., dst=...) failed.\") with no errno — the JVM API hides the real reason (cross-filesystem rename, missing/unwritable dst parent, existing dst, permissions).","triggerScenarios":"renameTo on a JVM without native Hadoop, where src and dst are on different mounts/filesystems, dst's parent does not exist or is not writable, dst already exists where the platform refuses overwrite, or src was concurrently removed.","commonSituations":"Moving spill/temp files between /tmp (often tmpfs) and a data directory; Windows installs missing hadoop.dll so the fallback always runs; destination parent never mkdir'd.","solutions":["Prefer java.nio.file.Files.move with ATOMIC_MOVE (fall back to REPLACE_EXISTING when atomic is unsupported) — it reports the actual failure reason.","Ensure dst.getParentFile() exists (mkdirs) and is writable, and that src/dst sit on the same filesystem.","Fix native loading (java.library.path → lib/native) so renameTo0 with real errno reporting is used."],"exampleFix":"// before\nNativeIO.renameTo(src, dst); // boolean fallback, no errno on failure\n\n// after\nimport static java.nio.file.StandardCopyOption.*;\ntry {\n  Files.move(src.toPath(), dst.toPath(), ATOMIC_MOVE);\n} catch (AtomicMoveNotSupportedException e) {\n  Files.move(src.toPath(), dst.toPath(), REPLACE_EXISTING);\n}","handlingStrategy":"fallback","validationCode":"if (!src.exists()) throw new java.io.FileNotFoundException(src.toString());\nFile parent = dst.getParentFile();\nif (parent != null && !parent.exists()) parent.mkdirs();","typeGuard":null,"tryCatchPattern":"try {\n  NativeIO.renameTo(src, dst);\n} catch (IOException e) {\n  if (!NativeIO.isAvailable()) {\n    // errno-less fallback failure: Files.move reports the real reason\n    Files.move(src.toPath(), dst.toPath(), REPLACE_EXISTING);\n  } else { throw e; }\n}","preventionTips":["Standardize new code on java.nio.file.Files.move.","Keep rename source and destination on the same volume for atomic semantics.","Create destination parent directories before renaming."],"tags":["native-io","rename","filesystem","java-fallback"],"backgroundTag":"rename-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}