apache/hadoop · error · IOException

map={} is negative. Please check {}

Error message

map={} is negative. Please check {}

What it means

RouterFederationRename.checkConfiguration validates fed-rename tuning before a job is built. The map count is read with default -1 from dfs.federation.router.federation.rename.map, so if the key is unset or set negative, this IOException is thrown telling you exactly which key to fix. 'map' is the number of distcp mappers the fed rename will request.

Source

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

  }

  void countIncrement() {
    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.map to a positive integer (e.g. number of distcp mappers like 10) in the router's hdfs-site.xml
2. Check for typos in the key name - a misspelled key silently falls back to -1
3. Set the companion keys too: dfs.federation.router.federation.rename.bandwidth (positive), and optionally .delay/.diff
4. Restart the router so the RPC server re-reads configuration

Example fix

# before: option enabled but map missing -> defaults to -1
<property><name>dfs.federation.router.federation.rename.option</name><value>DISTCP</value></property>
# after
<property><name>dfs.federation.router.federation.rename.option</name><value>DISTCP</value></property>
<property><name>dfs.federation.router.federation.rename.map</name><value>10</value></property>
<property><name>dfs.federation.router.federation.rename.bandwidth</name><value>128</value></property>

// Validate fed rename configuration before first use
int map = conf.getInt("dfs.federation.router.federation.rename.map", -1);
if (map < 0) {
  throw new IllegalStateException(
      "dfs.federation.router.federation.rename.map must be set to a positive int when fed rename is enabled");
}

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

When it happens

Trigger: A cross-namespace rename reaches buildRouterRenameJob / checkConfiguration while dfs.federation.router.federation.rename.map is absent from the router config or set to a negative value (the code reads conf.getInt(key, -1)).

Common situations: Enabling fed rename (option=DISTCP) but forgetting the required map/bandwidth settings; typo'd property name so the default -1 applies; porting an older config where keys were named differently.

Related errors

• Rename of {} to {} is not allowed, no eligible destination i
• bandwidth={} 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/f9f46dc2241f6b31. Report an issue: GitHub.