{"record":{"id":"b479d9dc961ddf33","repo":"apache/hadoop","slug":"async-queue-size-must-be-at-least-1","errorCode":null,"errorMessage":"Async queue size must be at least 1","messagePattern":"Async queue size 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":523,"sourceCode":"  /**\n   * Init router async handlers and router async responders.\n   * @param configuration the configuration.\n   */\n  public void initAsyncThreadPools(Configuration configuration) {\n    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,","sourceCodeStart":505,"sourceCodeEnd":541,"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#L505-L541","documentation":"Error \"Async queue size must be at least 1\" thrown in apache/hadoop.","triggerScenarios":"RouterRpcServer startup validation: configured async queue size is less than 1.","commonSituations":"Misconfiguration in hdfs-site.xml setting the async queue size to 0 or a negative number.","solutions":["Set dfs.federation.router.async.handler.queue.size (or the relevant async queue property) to a value >= 1.","Remove the property to use the default if an explicit 0/negative value was set by mistake."],"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"}