apache/hadoop · error · IllegalArgumentException

Async queue size must be at least 1

Error message

Async queue size must be at least 1

What it means

Error "Async queue size must be at least 1" thrown in apache/hadoop.

Source

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

  /**
   * Init router async handlers and router async responders.
   * @param configuration the configuration.
   */
  public void initAsyncThreadPools(Configuration configuration) {
    Set<String> allConfiguredNS = FederationUtil.getAllConfiguredNS(configuration);
    allConfiguredNS.add(CONCURRENT_NS);
    Map<String, Integer> nsAsyncActiveHandlerCount = parseNsAsyncHandlerCount(configuration);
    initAsyncHandlerThreadPools(configuration, allConfiguredNS, nsAsyncActiveHandlerCount);
    initAsyncResponderThreadPools(configuration);
  }

  private void initAsyncHandlerThreadPools(Configuration configuration,
      Set<String> allConfiguredNS, Map<String, Integer> nsAsyncHandlerCount) {
    LOG.info("Initializing asynchronous handler thread pools");
    int asyncQueueSize = configuration.getInt(DFS_ROUTER_ASYNC_RPC_QUEUE_SIZE,
        DFS_ROUTER_ASYNC_RPC_QUEUE_SIZE_DEFAULT);
    if (asyncQueueSize < 1) {
      throw new IllegalArgumentException("Async queue size must be at least 1");
    }
    int asyncHandlerCountDefault = configuration.getInt(DFS_ROUTER_ASYNC_RPC_HANDLER_COUNT_KEY,
        DFS_ROUTER_ASYNC_RPC_HANDLER_COUNT_DEFAULT);
    if (asyncHandlerCountDefault < 1) {
      throw new  IllegalArgumentException("Async handler count must be at least 1");
    }
    for (String nsId : allConfiguredNS) {
      int dedicatedHandlers = nsAsyncHandlerCount.getOrDefault(nsId, 0);
      if (dedicatedHandlers <= 0) {
        dedicatedHandlers = asyncHandlerCountDefault;
        LOG.info("Use default async handler count {} for ns {} to init Executors.",
            asyncHandlerCountDefault, nsId);
      } else {
        LOG.info("Dedicated handlers {} for ns {} to init Executors", dedicatedHandlers, nsId);
      }

      int finalDedicatedHandlers = dedicatedHandlers;
      asyncRouterHandlerExecutors.computeIfAbsent(nsId,

View on GitHub (pinned to 2add963021)

Solutions

1. Set dfs.federation.router.async.handler.queue.size (or the relevant async queue property) to a value >= 1.
2. Remove the property to use the default if an explicit 0/negative value was set by mistake.

When it happens

Trigger: RouterRpcServer startup validation: configured async queue size is less than 1.

Common situations: Misconfiguration in hdfs-site.xml setting the async queue size to 0 or a negative number.

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