{"record":{"id":"db1bca3eed4dd416","repo":"apache/hadoop","slug":"requested-queues-anumqueues-must-be-gre","errorCode":null,"errorMessage":"\"Requested queues (\" + aNumQueues + \") must be greater than zero.\"","messagePattern":"\"Requested queues \\(\" \\+ aNumQueues \\+ \"\\) must be greater than zero\\.\"","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/WeightedRoundRobinMultiplexer.java","lineNumber":59,"sourceCode":"public class WeightedRoundRobinMultiplexer implements RpcMultiplexer {\n  // Config keys\n  public static final String IPC_CALLQUEUE_WRRMUX_WEIGHTS_KEY =\n    \"faircallqueue.multiplexer.weights\";\n\n  public static final Logger LOG =\n      LoggerFactory.getLogger(WeightedRoundRobinMultiplexer.class);\n\n  private final int numQueues; // The number of queues under our provisioning\n\n  private final AtomicInteger currentQueueIndex; // Current queue we're serving\n  private final AtomicInteger requestsLeft; // Number of requests left for this queue\n\n  private int[] queueWeights; // The weights for each queue\n\n  public WeightedRoundRobinMultiplexer(int aNumQueues, String ns,\n    Configuration conf) {\n    if (aNumQueues <= 0) {\n      throw new IllegalArgumentException(\"Requested queues (\" + aNumQueues +\n        \") must be greater than zero.\");\n    }\n\n    this.numQueues = aNumQueues;\n    this.queueWeights = conf.getInts(ns + \".\" +\n      IPC_CALLQUEUE_WRRMUX_WEIGHTS_KEY);\n\n    if (this.queueWeights.length == 0) {\n      this.queueWeights = getDefaultQueueWeights(this.numQueues);\n    } else if (this.queueWeights.length != this.numQueues) {\n      throw new IllegalArgumentException(ns + \".\" +\n        IPC_CALLQUEUE_WRRMUX_WEIGHTS_KEY + \" must specify exactly \" +\n        this.numQueues + \" weights: one for each priority level.\");\n    }\n\n    this.currentQueueIndex = new AtomicInteger(0);\n    this.requestsLeft = new AtomicInteger(this.queueWeights[0]);\n","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/WeightedRoundRobinMultiplexer.java#L41-L77","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nipc.8020.callqueue.impl=org.apache.hadoop.ipc.FairCallQueue\nipc.8020.callqueue.priority-levels=0\n\n# after\nipc.8020.callqueue.impl=org.apache.hadoop.ipc.FairCallQueue\nipc.8020.callqueue.priority-levels=3","handlingStrategy":"validation","validationCode":"int levels = conf.getInt(\"ipc.\" + port + \".callqueue.priority-levels\", 0);\n// also check the non-deprecated ipc.<port>.scheduler.priority-levels if used\nif (levels <= 0 && usingFairCallQueue(conf, port)) {\n  throw new IllegalArgumentException(\n      \"ipc.\" + port + \".callqueue.priority-levels must be >= 1 when FairCallQueue is enabled\");\n}\n// now safe to start the server","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["hadoop","ipc","call-queue","faircallqueue","configuration","startup"],"backgroundTag":"invalid-config-value","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}