apache/hadoop · critical · IllegalArgumentException

Configured handlers dfs.federation.router.handler.count= %d

Error message

Configured handlers dfs.federation.router.handler.count= %d is less than the minimum required handlers %d

What it means

StaticRouterRpcFairnessPolicyController statically partitions the router's RPC handler threads across monitored nameservices: each NS gets dfs.federation.router.fairness.handler.count.<nsId> dedicated handlers (minimum 1 per NS if unset). At controller initialization it validates that dfs.federation.router.handler.count is at least the sum of all dedicated handlers; if not, it logs the formatted ERROR_MSG and throws IllegalArgumentException, preventing the router RPC server from starting.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/fairness/StaticRouterRpcFairnessPolicyController.java:125

  }

  private void validateHandlersCount(Configuration conf,
      int handlerCount, Set<String> allConfiguredNS) {
    int totalDedicatedHandlers = 0;
    for (String nsId : allConfiguredNS) {
      int dedicatedHandlers = conf.getInt(DFS_ROUTER_FAIR_HANDLER_COUNT_KEY_PREFIX + nsId, 0);
      if (dedicatedHandlers > 0) {
        // Total handlers should not be less than sum of dedicated handlers.
        totalDedicatedHandlers += dedicatedHandlers;
      } else {
        // Each NS should have at least one handler assigned.
        totalDedicatedHandlers++;
      }
    }
    if (totalDedicatedHandlers > handlerCount) {
      String msg = String.format(ERROR_MSG, handlerCount, totalDedicatedHandlers);
      LOG.error(msg);
      throw new IllegalArgumentException(msg);
    }
  }

}

View on GitHub (pinned to 2add963021)

Solutions

1. Count monitored namespaces and all dfs.federation.router.fairness.handler.count.<nsId> settings; raise dfs.federation.router.handler.count to at least that sum
2. Remove or lower per-namespace dfs.federation.router.fairness.handler.count.<nsId> overrides you do not need
3. Restart the router and confirm the RPC server starts and reaches ACTIVE state

Example fix

<!-- before: 3 monitored namespaces need >=3 handlers, only 2 configured -->
<property>
  <name>dfs.federation.router.handler.count</name>
  <value>2</value>
</property>
<!-- after -->
<property>
  <name>dfs.federation.router.handler.count</name>
  <value>10</value>
</property>

// Pre-flight config check mirroring the controller's validation
int handlers = conf.getInt("dfs.federation.router.handler.count", 10);
int required = 0;
for (String ns : monitoredNameservices(conf)) {
  required += Math.max(1,
      conf.getInt("dfs.federation.router.fairness.handler.count." + ns, 0));
}
if (required > handlers) {
  throw new IllegalArgumentException(
      "dfs.federation.router.handler.count=" + handlers
          + " must be >= sum of per-NS handlers " + required);
}

When it happens

Trigger: dfs.federation.router.handler.count (default 10) set below the number of monitored nameservices (each implicitly requires >=1 handler), or the sum of explicit dfs.federation.router.fairness.handler.count.<nsId> values exceeds the configured total handler count.

Common situations: Scaling federation up (adding namespaces) without raising handler count; tuning handler.count down for memory while leaving per-NS fairness allocations in place; using the default handler count with more than 10 monitored namespaces.

Related errors

• Wrong name service specified : {}
• State Store does not have an interface for {}
• Cannot find locations for {}, because the default nameservic
• Mount Table not initialized
• Mount table state store is not available.

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