apache/hadoop · critical · IllegalArgumentException

callqueue.capacity.weights must specify

Error message

callqueue.capacity.weights must specify ${priorityLevels} capacity weights: one for each priority level

What it means

CallQueueManager.parseCapacityWeights reads ipc.<port>.callqueue.capacity.weights (an int list). If the list is empty, equal default weights are used; if it is non-empty but its length differs from the configured scheduler priority levels, this IllegalArgumentException is thrown because each priority level needs exactly one capacity weight.

Solutions

Count your weights and make them equal ipc.<port>.scheduler.priority.levels (e.g., '10,5,3,1' for 4 levels).
Or remove callqueue.capacity.weights entirely to get equal default weights per level.
Double-check the effective priority levels value — the mismatch is often on the levels side, not the weights side.
Watch for the deprecated ipc.<port>.callqueue.priority.levels overriding your intended level count.

Example fix

# before
<property><name>ipc.8020.scheduler.priority.levels</name><value>4</value></property>
<property><name>ipc.8020.callqueue.capacity.weights</name><value>4,3</value></property> <!-- 2 != 4 -->

# after
<property><name>ipc.8020.callqueue.capacity.weights</name><value>4,3,2,1</value></property>

Defensive patterns

Strategy: validation

Validate before calling

int levels = conf.getInt("ipc.8020.scheduler.priority.levels", 4);
int[] weights = conf.getInts("ipc.8020.callqueue.capacity.weights");
if (weights != null && weights.length > 0) {
  Preconditions.checkArgument(weights.length == levels,
      "need exactly %s weights, got %s", levels, weights.length);
}

Prevention

Derive the weights count from the configured priority levels in config templates.
Prefer omitting callqueue.capacity.weights unless you truly need unequal capacities.
Automated config checks (CI or Ambari/Cloudera validation) for paired ipc.* keys.

When it happens

Trigger: Setting ipc.<port>.callqueue.capacity.weights to a comma-separated list whose count differs from ipc.<port>.scheduler.priority.levels — e.g., weights '4,3,2,1' while priority.levels is 5, or a single '3' while levels is the default 4.

Common situations: Tuning FairCallQueue capacity distribution on NameNode/ResourceManager ports; changing scheduler.priority.levels without updating the weights list; trailing commas or parsing artifacts producing a different element count than intended.

Related errors

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

Appendix: source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/CallQueueManager.java:424

    }
    if(retval < 1) {
      throw new IllegalArgumentException("numLevels must be at least 1");
    }
    return retval;
  }

  /**
   * Read the weights of capacity in callqueue and pass the value to
   * callqueue constructions.
   */
  private static int[] parseCapacityWeights(
      int priorityLevels, String ns, Configuration conf) {
    int[] weights = conf.getInts(ns + "." +
      CommonConfigurationKeys.IPC_CALLQUEUE_CAPACITY_WEIGHTS_KEY);
    if (weights.length == 0) {
      weights = getDefaultQueueCapacityWeights(priorityLevels);
    } else if (weights.length != priorityLevels) {
      throw new IllegalArgumentException(
          CommonConfigurationKeys.IPC_CALLQUEUE_CAPACITY_WEIGHTS_KEY + " must "
              + "specify " + priorityLevels + " capacity weights: one for each "
              + "priority level");
    } else {
      // only allow positive numbers
      for (int w : weights) {
        if (w <= 0) {
          throw new IllegalArgumentException(
              CommonConfigurationKeys.IPC_CALLQUEUE_CAPACITY_WEIGHTS_KEY +
                  " only takes positive weights. " + w + " capacity weight " +
                  "found");
        }
      }
    }
    return weights;
  }

  /**

View on GitHub (pinned to 2add963021)