apache/hadoop · error · IOException

Rename of {} to {} failed.

Error message

Rename of {} to {} failed.

What it means

Router federation rename runs as a BalanceJob on the BalanceProcedureScheduler (a distcp-based procedure framework). After scheduler.waitUntilDone(job), RouterFederationRename checks job.getError(); a non-null error means the procedure (job submit, distcp phases, or finalization) failed, and it is rethrown wrapped in this IOException with the original cause attached.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/RouterFederationRename.java:130

    UserGroupInformation routerUser = UserGroupInformation.getLoginUser();

    try {
      // as router user with saveJournal and task submission privileges
      return routerUser.doAs((PrivilegedExceptionAction<Boolean>) () -> {
        // Build and submit router federation rename job.
        BalanceJob job = buildRouterRenameJob(srcLoc.getNameserviceId(),
            dstLoc.getNameserviceId(), srcLoc.getDest(), dstLoc.getDest());
        BalanceProcedureScheduler scheduler = rpcServer.getFedRenameScheduler();
        countIncrement();
        try {
          scheduler.submit(job);
          LOG.info("Rename {} to {} from namespace {} to {}. JobId={}.", src,
              dst, srcLoc.getNameserviceId(), dstLoc.getNameserviceId(),
              job.getId());
          scheduler.waitUntilDone(job);
          if (job.getError() != null) {
            throw new IOException("Rename of " + src + " to " + dst +
                " failed.", job.getError());
          }
          return true;
        } finally {
          countDecrement();
        }
      });
    } catch (InterruptedException e) {
      LOG.warn("Fed balance job is interrupted.", e);
      throw new InterruptedIOException(e.getMessage());
    }
  }

  /**
   * Check router federation rename permission.
   */
  private void checkPermission(RemoteLocation src, RemoteLocation dst)
      throws IOException {

View on GitHub (pinned to 2add963021)

Solutions

1. Inspect the wrapped cause (job.getError()) and the router log for the BalanceJob id logged at submit time; it names the failing phase
2. Verify both source and destination nameservices are up and reachable from the router when retrying
3. Check state store health (ZK/JDBC) since procedure journals persist there; clear stale procedure state if the scheduler refuses to run
4. Re-run the rename after fixing the root cause; fed rename is idempotent enough for a retry once the underlying fault is cleared

// Confirm both nameservices and the fed rename scheduler are healthy before rename
for (String ns : new String[]{srcNs, dstNs}) {
  if (!namenodeResolver.getNamespaces().stream()
      .anyMatch(i -> i.getNameserviceId().equals(ns))) {
    throw new IllegalStateException("Nameservice unavailable: " + ns);
  }
}

try {
  routerFedRename.routerFedRename(src, dst, srcLocs, dstLocs);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Rename of ")
      && e.getMessage().endsWith("failed.") && e.getCause() != null) {
    LOG.warn("Fed rename job failed, cause:", e.getCause()); // inspect job.getError() cause before retry
  }
  throw e;
}

When it happens

Trigger: A fed rename job was submitted and completed with an error state: distcp map task failures, source/destination cluster unreachable during the job, scheduler not running when submit() was called, state store failure while persisting job records, or the job's procedures erroring (e.g. RENAME phase failing on the target nameservice).

Common situations: Transient subcluster outage mid-copy; router state store (ZK) hiccups while the balance procedure persists journals; distcp failing on file contention or permission issues at job time; scheduler threads killed during router shutdown while a rename was in flight.

Related errors

• Rename of {} to {} is not allowed, no eligible destination i
• Rename of {} to {} is not allowed. The remote location shoul
• Permission denied rename {}({}) to {}({}) Reason={}
• Router Federation Rename is interrupted while checking permi
• Router federation rename can't rename snapshot path. src={}(

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