apache/hadoop · error · IllegalArgumentException

"Requested queues (" + aNumQueues + ") must be greater than

Error message

"Requested queues (" + aNumQueues + ") must be greater than zero."

What it means

WeightedRoundRobinMultiplexer is the multiplexer FairCallQueue uses to decide which priority queue to serve next. Its constructor requires at least one queue; the queue count comes from the call queue priority-levels configuration (ns + '.' + FairCallQueue.IPC_CALLQUEUE_PRIORITY_LEVELS_KEY or the newer scheduler priority-levels key, ns is 'ipc.<port>.callqueue'). A zero or negative value throws IllegalArgumentException at server construction, preventing daemon startup.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/WeightedRoundRobinMultiplexer.java:59

public class WeightedRoundRobinMultiplexer implements RpcMultiplexer {
  // Config keys
  public static final String IPC_CALLQUEUE_WRRMUX_WEIGHTS_KEY =
    "faircallqueue.multiplexer.weights";

  public static final Logger LOG =
      LoggerFactory.getLogger(WeightedRoundRobinMultiplexer.class);

  private final int numQueues; // The number of queues under our provisioning

  private final AtomicInteger currentQueueIndex; // Current queue we're serving
  private final AtomicInteger requestsLeft; // Number of requests left for this queue

  private int[] queueWeights; // The weights for each queue

  public WeightedRoundRobinMultiplexer(int aNumQueues, String ns,
    Configuration conf) {
    if (aNumQueues <= 0) {
      throw new IllegalArgumentException("Requested queues (" + aNumQueues +
        ") must be greater than zero.");
    }

    this.numQueues = aNumQueues;
    this.queueWeights = conf.getInts(ns + "." +
      IPC_CALLQUEUE_WRRMUX_WEIGHTS_KEY);

    if (this.queueWeights.length == 0) {
      this.queueWeights = getDefaultQueueWeights(this.numQueues);
    } else if (this.queueWeights.length != this.numQueues) {
      throw new IllegalArgumentException(ns + "." +
        IPC_CALLQUEUE_WRRMUX_WEIGHTS_KEY + " must specify exactly " +
        this.numQueues + " weights: one for each priority level.");
    }

    this.currentQueueIndex = new AtomicInteger(0);
    this.requestsLeft = new AtomicInteger(this.queueWeights[0]);

View on GitHub (pinned to 2add963021)

Solutions

Set the priority levels key to >=1 (typical values are 2-4), e.g. ipc.8020.callqueue.priority-levels=3 or the non-deprecated ipc.<port>.scheduler.priority-levels equivalent.
Or remove the FairCallQueue/multiplexer configuration entirely to fall back to the default single LinkedBlockingQueue call queue.
If constructing the multiplexer programmatically, validate the queue count is positive before the constructor call.

Example fix

# before
ipc.8020.callqueue.impl=org.apache.hadoop.ipc.FairCallQueue
ipc.8020.callqueue.priority-levels=0

# after
ipc.8020.callqueue.impl=org.apache.hadoop.ipc.FairCallQueue
ipc.8020.callqueue.priority-levels=3

Defensive patterns

Strategy: validation

Validate before calling

int levels = conf.getInt("ipc." + port + ".callqueue.priority-levels", 0);
// also check the non-deprecated ipc.<port>.scheduler.priority-levels if used
if (levels <= 0 && usingFairCallQueue(conf, port)) {
  throw new IllegalArgumentException(
      "ipc." + port + ".callqueue.priority-levels must be >= 1 when FairCallQueue is enabled");
}
// now safe to start the server

Prevention

When enabling FairCallQueue, set priority-levels (>=1, typically 2-4) in the same change and review both keys together.
Add a pre-flight config validator to deployment tooling that checks every ipc.<port>.* key the change introduces.
Prefer the non-deprecated scheduler priority-levels key on current Hadoop versions.

When it happens

Trigger: Configuring ipc.<port>.callqueue.impl=org.apache.hadoop.ipc.FairCallQueue (or DecayRpcScheduler priorities) with priority-levels set to 0 or negative, e.g. ipc.8020.callqueue.priority-levels=0; or instantiating new WeightedRoundRobinMultiplexer(0, ns, conf) directly in code/tests.

Common situations: Tuning NameNode/ResourceManager call queues and typo'ing the priority-levels value; copy-pasting a partial FairCallQueue recipe from blog posts; automation scripts computing the queue count that can evaluate to 0.

Related errors

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