apache/hadoop · error · IllegalArgumentException

Number of Priority Levels must be at least 1

Error message

Number of Priority Levels must be at least 1

What it means

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.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/FairCallQueue.java:122

  /**
   * Create a FairCallQueue.
   * @param priorityLevels the total size of all multi-level queue
   *                       priority policies
   * @param capacity the total size of all sub-queues
   * @param ns the prefix to use for configuration
   * @param capacityWeights the weights array for capacity allocation
   *                        among subqueues
   * @param serverFailOverEnabled whether or not to enable callqueue overflow trigger failover
   *                              for stateless servers when RPC call queue is filled
   * @param conf the configuration to read from
   * Notes: Each sub-queue has a capacity of `capacity / numSubqueues`.
   * The first or the highest priority sub-queue has an excess capacity
   * of `capacity % numSubqueues`
   */
  public FairCallQueue(int priorityLevels, int capacity, String ns,
      int[] capacityWeights, boolean serverFailOverEnabled, Configuration conf) {
    if(priorityLevels < 1) {
      throw new IllegalArgumentException("Number of Priority Levels must be " +
          "at least 1");
    }
    int numQueues = priorityLevels;
    this.serverFailOverEnabled = serverFailOverEnabled;
    LOG.info("FairCallQueue is in use with " + numQueues +
        " queues with total capacity of " + capacity);

    this.queues = new ArrayList<BlockingQueue<E>>(numQueues);
    this.overflowedCalls = new ArrayList<AtomicLong>(numQueues);
    int totalWeights = 0;
    for (int i = 0; i < capacityWeights.length; i++) {
      totalWeights += capacityWeights[i];
    }
    int residueCapacity = capacity % totalWeights;
    int unitCapacity = capacity / totalWeights;
    int queueCapacity;
    for(int i=0; i < numQueues; i++) {
      queueCapacity = unitCapacity * capacityWeights[i];

View on GitHub (pinned to 2add963021)

Solutions

1. Set ipc.<port>.callqueue-priority-levels to >= 1 (keep it consistent with decay-scheduler.thresholds count) and restart the daemon.
2. If levels were zeroed to 'simplify', remove the key to restore the default instead.
3. For programmatic use, validate priorityLevels >= 1 before constructing FairCallQueue.

Example fix

// before (core-site.xml)
<property><name>ipc.8020.callqueue-priority-levels</name><value>0</value></property>
<property><name>ipc.8020.callqueue.impl</name><value>org.apache.hadoop.ipc.FairCallQueue</value></property>
<!-- FairCallQueue ctor throws IllegalArgumentException -->

// after
<property><name>ipc.8020.callqueue-priority-levels</name><value>4</value></property>

int levels = conf.getInt("ipc." + port + ".callqueue-priority-levels", 1);
if (levels < 1) {
  throw new ConfigException("callqueue-priority-levels must be >= 1 when FairCallQueue is enabled, got " + levels);
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• Number of Priority Levels must be at least 1
• Decay Factor must be between 0 and 1
• Period millis must be >= 0
• "Requested queues (" + aNumQueues + ") must be greater than
• ${theClass.getName()} could not be constructed.

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