apache/hadoop · error · IllegalArgumentException

Async handler count must be at least 1

Error message

Async handler count must be at least 1

What it means

Error "Async handler count 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:528

    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,
          id -> {
            LinkedBlockingQueue<Runnable> queue = new LinkedBlockingQueue<>(asyncQueueSize);
            return new ThreadPoolExecutor(finalDedicatedHandlers, finalDedicatedHandlers,
                0L, TimeUnit.MILLISECONDS, queue,
                new AsyncThreadFactory("Router Async Handler for " + nsId + " #"));

View on GitHub (pinned to 2add963021)

Solutions

1. Set the async handler count property (dfs.federation.router.async.handler.count) to at least 1.
2. Delete the invalid override so the default handler count applies.

When it happens

Trigger: RouterRpcServer startup validation: configured async handler count is less than 1.

Common situations: Configuration error setting async handlers to 0 or negative in the Router's hdfs-site.xml.

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