apache/hadoop · error · IOException

diff={} is negative. Please check {}

Error message

diff={} is negative. Please check {}

What it means

checkConfiguration validates the fed-rename diff threshold read from dfs.federation.router.federation.rename.diff (default 0, meaning the check passes unless explicitly set negative). 'diff' bounds the allowed difference when the rename procedure compares src/dst states before finalizing; a negative value is rejected before a job is submitted.

Source

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

  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.diff to a non-negative integer (default 0) or drop the key from the config
2. Sanity-check all four fed-rename numeric keys (map, bandwidth, delay, diff) with a config linter before deploying
3. Restart the router after the fix

Example fix

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

int diff = conf.getInt("dfs.federation.router.federation.rename.diff", 0);
if (diff < 0) {
  throw new IllegalStateException(
      "dfs.federation.router.federation.rename.diff must be non-negative (0 is the neutral default)");
}

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

When it happens

Trigger: dfs.federation.router.federation.rename.diff is explicitly set to a negative integer in the router configuration and a cross-namespace rename runs checkConfiguration.

Common situations: Placeholder -1 values from templates; mistaken belief that -1 disables the diff check (it does not - 0 is the neutral value); hand-edited configs where a stray minus sign slips in.

Related errors

• Rename of {} to {} is not allowed, no eligible destination i
• map={} is negative. Please check {}
• bandwidth={} is negative. Please check {}
• delay={} 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/4aa0e79753846d81. Report an issue: GitHub.