{"record":{"id":"edbf207aa0dfce7a","repo":"apache/hadoop","slug":"async-handler-count-must-be-at-least-1","errorCode":null,"errorMessage":"Async handler count must be at least 1","messagePattern":"Async handler count must be at least 1","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/RouterRpcServer.java","lineNumber":528,"sourceCode":"    Set<String> allConfiguredNS = FederationUtil.getAllConfiguredNS(configuration);\n    allConfiguredNS.add(CONCURRENT_NS);\n    Map<String, Integer> nsAsyncActiveHandlerCount = parseNsAsyncHandlerCount(configuration);\n    initAsyncHandlerThreadPools(configuration, allConfiguredNS, nsAsyncActiveHandlerCount);\n    initAsyncResponderThreadPools(configuration);\n  }\n\n  private void initAsyncHandlerThreadPools(Configuration configuration,\n      Set<String> allConfiguredNS, Map<String, Integer> nsAsyncHandlerCount) {\n    LOG.info(\"Initializing asynchronous handler thread pools\");\n    int asyncQueueSize = configuration.getInt(DFS_ROUTER_ASYNC_RPC_QUEUE_SIZE,\n        DFS_ROUTER_ASYNC_RPC_QUEUE_SIZE_DEFAULT);\n    if (asyncQueueSize < 1) {\n      throw new IllegalArgumentException(\"Async queue size must be at least 1\");\n    }\n    int asyncHandlerCountDefault = configuration.getInt(DFS_ROUTER_ASYNC_RPC_HANDLER_COUNT_KEY,\n        DFS_ROUTER_ASYNC_RPC_HANDLER_COUNT_DEFAULT);\n    if (asyncHandlerCountDefault < 1) {\n      throw new  IllegalArgumentException(\"Async handler count must be at least 1\");\n    }\n    for (String nsId : allConfiguredNS) {\n      int dedicatedHandlers = nsAsyncHandlerCount.getOrDefault(nsId, 0);\n      if (dedicatedHandlers <= 0) {\n        dedicatedHandlers = asyncHandlerCountDefault;\n        LOG.info(\"Use default async handler count {} for ns {} to init Executors.\",\n            asyncHandlerCountDefault, nsId);\n      } else {\n        LOG.info(\"Dedicated handlers {} for ns {} to init Executors\", dedicatedHandlers, nsId);\n      }\n\n      int finalDedicatedHandlers = dedicatedHandlers;\n      asyncRouterHandlerExecutors.computeIfAbsent(nsId,\n          id -> {\n            LinkedBlockingQueue<Runnable> queue = new LinkedBlockingQueue<>(asyncQueueSize);\n            return new ThreadPoolExecutor(finalDedicatedHandlers, finalDedicatedHandlers,\n                0L, TimeUnit.MILLISECONDS, queue,\n                new AsyncThreadFactory(\"Router Async Handler for \" + nsId + \" #\"));","sourceCodeStart":510,"sourceCodeEnd":546,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-rbf/src/main/java/org/apache/hadoop/hdfs/server/federation/router/RouterRpcServer.java#L510-L546","documentation":"Error \"Async handler count must be at least 1\" thrown in apache/hadoop.","triggerScenarios":"RouterRpcServer startup validation: configured async handler count is less than 1.","commonSituations":"Configuration error setting async handlers to 0 or negative in the Router's hdfs-site.xml.","solutions":["Set the async handler count property (dfs.federation.router.async.handler.count) to at least 1.","Delete the invalid override so the default handler count applies."],"exampleFix":null,"handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}