{"record":{"id":"a8e1a183bbdf0e7d","repo":"apache/hadoop","slug":"number-of-priority-levels-must-be-at-least-1-a8e1a1","errorCode":null,"errorMessage":"Number of Priority Levels must be at least 1","messagePattern":"Number of Priority Levels must be at least 1","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/FairCallQueue.java","lineNumber":122,"sourceCode":"  /**\n   * Create a FairCallQueue.\n   * @param priorityLevels the total size of all multi-level queue\n   *                       priority policies\n   * @param capacity the total size of all sub-queues\n   * @param ns the prefix to use for configuration\n   * @param capacityWeights the weights array for capacity allocation\n   *                        among subqueues\n   * @param serverFailOverEnabled whether or not to enable callqueue overflow trigger failover\n   *                              for stateless servers when RPC call queue is filled\n   * @param conf the configuration to read from\n   * Notes: Each sub-queue has a capacity of `capacity / numSubqueues`.\n   * The first or the highest priority sub-queue has an excess capacity\n   * of `capacity % numSubqueues`\n   */\n  public FairCallQueue(int priorityLevels, int capacity, String ns,\n      int[] capacityWeights, boolean serverFailOverEnabled, Configuration conf) {\n    if(priorityLevels < 1) {\n      throw new IllegalArgumentException(\"Number of Priority Levels must be \" +\n          \"at least 1\");\n    }\n    int numQueues = priorityLevels;\n    this.serverFailOverEnabled = serverFailOverEnabled;\n    LOG.info(\"FairCallQueue is in use with \" + numQueues +\n        \" queues with total capacity of \" + capacity);\n\n    this.queues = new ArrayList<BlockingQueue<E>>(numQueues);\n    this.overflowedCalls = new ArrayList<AtomicLong>(numQueues);\n    int totalWeights = 0;\n    for (int i = 0; i < capacityWeights.length; i++) {\n      totalWeights += capacityWeights[i];\n    }\n    int residueCapacity = capacity % totalWeights;\n    int unitCapacity = capacity / totalWeights;\n    int queueCapacity;\n    for(int i=0; i < numQueues; i++) {\n      queueCapacity = unitCapacity * capacityWeights[i];","sourceCodeStart":104,"sourceCodeEnd":140,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/FairCallQueue.java#L104-L140","documentation":"FairCallQueue's constructor mirrors DecayRpcScheduler's guard: the queue is built as one BlockingQueue per priority level, so priorityLevels < 1 makes queue construction meaningless and throws IllegalArgumentException during RPC server startup. priorityLevels is supplied by CallQueueManager from ipc.<port>.callqueue-priority-levels when the fair callqueue (scheduler/callqueue impl) is selected.","triggerScenarios":"ipc.<port>.callqueue-priority-levels set to 0 or negative on a server configured with callqueue.impl=FairCallQueue (directly or via scheduler settings); constructing FairCallQueue in tests with priorityLevels=0.","commonSituations":"Tuning scripts that zero out queue levels; inconsistent config where the level key is set but the callqueue implementation changed; smoke tests constructing the queue directly.","solutions":["Set ipc.<port>.callqueue-priority-levels to >= 1 (keep it consistent with decay-scheduler.thresholds count) and restart the daemon.","If levels were zeroed to 'simplify', remove the key to restore the default instead.","For programmatic use, validate priorityLevels >= 1 before constructing FairCallQueue."],"exampleFix":"// before (core-site.xml)\n<property><name>ipc.8020.callqueue-priority-levels</name><value>0</value></property>\n<property><name>ipc.8020.callqueue.impl</name><value>org.apache.hadoop.ipc.FairCallQueue</value></property>\n<!-- FairCallQueue ctor throws IllegalArgumentException -->\n\n// after\n<property><name>ipc.8020.callqueue-priority-levels</name><value>4</value></property>","handlingStrategy":"validation","validationCode":"int levels = conf.getInt(\"ipc.\" + port + \".callqueue-priority-levels\", 1);\nif (levels < 1) {\n  throw new ConfigException(\"callqueue-priority-levels must be >= 1 when FairCallQueue is enabled, got \" + levels);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["With callqueue.impl=FairCallQueue, keep priority levels >= 1.","Validate the whole callqueue/scheduler config group atomically at startup.","Prefer removing tuning keys you do not understand over zeroing them."],"tags":["hadoop","ipc","faircallqueue","callqueue","config","startup"],"backgroundTag":"config-validation-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}