{"record":{"id":"a94e172222a4b150","repo":"apache/hadoop","slug":"configured-handlers-dfs-federation-router-handler","errorCode":null,"errorMessage":"Configured handlers dfs.federation.router.handler.count= %d is less than the minimum required handlers %d","messagePattern":"Configured handlers dfs\\.federation\\.router\\.handler\\.count= (.+?) is less than the minimum required handlers (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/fairness/StaticRouterRpcFairnessPolicyController.java","lineNumber":125,"sourceCode":"  }\n\n  private void validateHandlersCount(Configuration conf,\n      int handlerCount, Set<String> allConfiguredNS) {\n    int totalDedicatedHandlers = 0;\n    for (String nsId : allConfiguredNS) {\n      int dedicatedHandlers = conf.getInt(DFS_ROUTER_FAIR_HANDLER_COUNT_KEY_PREFIX + nsId, 0);\n      if (dedicatedHandlers > 0) {\n        // Total handlers should not be less than sum of dedicated handlers.\n        totalDedicatedHandlers += dedicatedHandlers;\n      } else {\n        // Each NS should have at least one handler assigned.\n        totalDedicatedHandlers++;\n      }\n    }\n    if (totalDedicatedHandlers > handlerCount) {\n      String msg = String.format(ERROR_MSG, handlerCount, totalDedicatedHandlers);\n      LOG.error(msg);\n      throw new IllegalArgumentException(msg);\n    }\n  }\n\n}\n","sourceCodeStart":107,"sourceCodeEnd":130,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/fairness/StaticRouterRpcFairnessPolicyController.java#L107-L130","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Count monitored namespaces and all dfs.federation.router.fairness.handler.count.<nsId> settings; raise dfs.federation.router.handler.count to at least that sum","Remove or lower per-namespace dfs.federation.router.fairness.handler.count.<nsId> overrides you do not need","Restart the router and confirm the RPC server starts and reaches ACTIVE state"],"exampleFix":"<!-- before: 3 monitored namespaces need >=3 handlers, only 2 configured -->\n<property>\n  <name>dfs.federation.router.handler.count</name>\n  <value>2</value>\n</property>\n<!-- after -->\n<property>\n  <name>dfs.federation.router.handler.count</name>\n  <value>10</value>\n</property>","handlingStrategy":"validation","validationCode":"// Pre-flight config check mirroring the controller's validation\nint handlers = conf.getInt(\"dfs.federation.router.handler.count\", 10);\nint required = 0;\nfor (String ns : monitoredNameservices(conf)) {\n  required += Math.max(1,\n      conf.getInt(\"dfs.federation.router.fairness.handler.count.\" + ns, 0));\n}\nif (required > handlers) {\n  throw new IllegalArgumentException(\n      \"dfs.federation.router.handler.count=\" + handlers\n          + \" must be >= sum of per-NS handlers \" + required);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When adding namespaces, re-check handler count against the sum of per-NS fairness allocations","Leave headroom above the sum (extra handlers for the shared/default pool)","Assert this invariant in config-management templates (ansible/puppet) before rollout"],"tags":["hadoop","rbf","router","fairness","configuration","startup"],"backgroundTag":"invalid-configuration-value","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}