apache/hadoop · error · IOException

bandwidth={} is negative. Please check {}

Error message

bandwidth={} is negative. Please check {}

What it means

checkConfiguration validates the fed-rename distcp bandwidth limit read from dfs.federation.router.federation.rename.bandwidth with default -1. If the key is unset or negative, the router throws this IOException before building the rename job; 'bandwidth' caps per-mapper copy bandwidth (MB/s) for the underlying distcp.

Source

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

    routerRenameCounter.incrementAndGet();
  }

  void countDecrement() {
    routerRenameCounter.decrementAndGet();
  }

  static void checkConfiguration(Configuration conf) throws IOException {
    int map = conf.getInt(DFS_ROUTER_FEDERATION_RENAME_MAP, -1);
    int bandwidth = conf.getInt(DFS_ROUTER_FEDERATION_RENAME_BANDWIDTH, -1);
    long delay = conf.getLong(DFS_ROUTER_FEDERATION_RENAME_DELAY,
        DFS_ROUTER_FEDERATION_RENAME_DELAY_DEFAULT);
    int diff = conf.getInt(DFS_ROUTER_FEDERATION_RENAME_DIFF,
        DFS_ROUTER_FEDERATION_RENAME_DIFF_DEFAULT);
    if (map < 0) {
      throw new IOException("map=" + map + " is negative. Please check "
          + DFS_ROUTER_FEDERATION_RENAME_MAP);
    } else if (bandwidth < 0) {
      throw new IOException(
          "bandwidth=" + bandwidth + " is negative. Please check "
              + DFS_ROUTER_FEDERATION_RENAME_BANDWIDTH);
    } else if (delay < 0) {
      throw new IOException("delay=" + delay + " is negative. Please check "
          + DFS_ROUTER_FEDERATION_RENAME_DELAY);
    } else if (diff < 0) {
      throw new IOException("diff=" + diff + " is negative. Please check "
          + DFS_ROUTER_FEDERATION_RENAME_DIFF);
    }
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Set dfs.federation.router.federation.rename.bandwidth to a non-negative value (positive MB/s limit; 0 = unlimited) in the router config
2. Verify the exact key spelling: dfs.federation.router.federation.rename.bandwidth
3. Configure map/bandwidth/delay/diff together when enabling fed rename and restart the router

Example fix

# before
<property><name>dfs.federation.router.federation.rename.bandwidth</name><value>-1</value></property>
# after
<property><name>dfs.federation.router.federation.rename.bandwidth</name><value>100</value></property>

int bandwidth = conf.getInt("dfs.federation.router.federation.rename.bandwidth", -1);
if (bandwidth < 0) {
  throw new IllegalStateException(
      "dfs.federation.router.federation.rename.bandwidth must be non-negative (0 = unlimited)");
}

try {
  routerFedRename.routerFedRename(src, dst, srcLocs, dstLocs);
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("dfs.federation.router.federation.rename.bandwidth")) {
    // set the bandwidth key named in the message, restart router, retry
  }
  throw e;
}

When it happens

Trigger: Cross-namespace rename with dfs.federation.router.federation.rename.bandwidth missing from the router configuration (getInt default -1) or explicitly set to a negative number.

Common situations: Partial fed-rename configuration (option and map set, bandwidth forgotten); copying configs between clusters where the bandwidth key was dropped; deliberate '0 means unlimited' confusion - 0 is accepted but negative is not.

Related errors

• Rename of {} to {} is not allowed, no eligible destination i
• map={} is negative. Please check {}
• delay={} is negative. Please check {}
• diff={} is negative. Please check {}
• Rename of {} to {} is not allowed. The remote location shoul

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