apache/hadoop · error · IOException

renameTo(src=${src}, dst=${dst}) failed.

Error message

renameTo(src=${src}, dst=${dst}) failed.

What it means

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).

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/nativeio/NativeIO.java:1068

      LOG.info("Initialized cache for UID to User mapping with a cache" +
          " timeout of " + cacheTimeout/1000 + " seconds.");
      initialized = true;
    }
  }
  
  /**
   * A version of renameTo that throws a descriptive exception when it fails.
   *
   * @param src                  The source path
   * @param dst                  The destination path
   * 
   * @throws NativeIOException   On failure.
   */
  public static void renameTo(File src, File dst)
      throws IOException {
    if (!nativeLoaded) {
      if (!src.renameTo(dst)) {
        throw new IOException("renameTo(src=" + src + ", dst=" +
          dst + ") failed.");
      }
    } else {
      renameTo0(src.getAbsolutePath(), dst.getAbsolutePath());
    }
  }

  /**
   * Creates a hardlink "dst" that points to "src".
   *
   * This is deprecated since JDK7 NIO can create hardlinks via the
   * {@link java.nio.file.Files} API.
   *
   * @param src source file
   * @param dst hardlink location
   * @throws IOException raised on errors performing I/O.
   */
  @Deprecated

View on GitHub (pinned to 2add963021)

Solutions

1. Prefer java.nio.file.Files.move with ATOMIC_MOVE (fall back to REPLACE_EXISTING when atomic is unsupported) — it reports the actual failure reason.
2. Ensure dst.getParentFile() exists (mkdirs) and is writable, and that src/dst sit on the same filesystem.
3. Fix native loading (java.library.path → lib/native) so renameTo0 with real errno reporting is used.

Example fix

// before
NativeIO.renameTo(src, dst); // boolean fallback, no errno on failure

// after
import static java.nio.file.StandardCopyOption.*;
try {
  Files.move(src.toPath(), dst.toPath(), ATOMIC_MOVE);
} catch (AtomicMoveNotSupportedException e) {
  Files.move(src.toPath(), dst.toPath(), REPLACE_EXISTING);
}

if (!src.exists()) throw new java.io.FileNotFoundException(src.toString());
File parent = dst.getParentFile();
if (parent != null && !parent.exists()) parent.mkdirs();

try {
  NativeIO.renameTo(src, dst);
} catch (IOException e) {
  if (!NativeIO.isAvailable()) {
    // errno-less fallback failure: Files.move reports the real reason
    Files.move(src.toPath(), dst.toPath(), REPLACE_EXISTING);
  } else { throw e; }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Failed to rename {from} to {to} due to failure in native ren
• Could not rename temporary file {} to {} due to failure in n
• Cannot overwrite an existing file: %s
• Cannot rename because path does not exist: %s
• Rename unsuccessful : '%s' to '%s'

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/4f03c8ca7fa91f5b. Report an issue: GitHub.