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

DecayRpcScheduler's constructor validates numLevels: with fewer than one priority level the decay scheduler cannot bucket calls, so it throws IllegalArgumentException during server startup. numLevels comes from the callqueue priority-levels setting (ipc.<port>.callqueue-priority-levels) read by CallQueueManager when the FairCallQueue + DecayRpcScheduler combo is configured.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/DecayRpcScheduler.java:238

      } else {
        // Our scheduler was garbage collected since it is no longer in use,
        // so we should terminate the timer as well
        timer.cancel();
        timer.purge();
      }
    }
  }

  /**
   * Create a decay scheduler.
   * @param numLevels number of priority levels
   * @param ns config prefix, so that we can configure multiple schedulers
   *           in a single instance.
   * @param conf configuration to use.
   */
  public DecayRpcScheduler(int numLevels, String ns, Configuration conf) {
    if(numLevels < 1) {
      throw new IllegalArgumentException("Number of Priority Levels must be " +
          "at least 1");
    }
    this.numLevels = numLevels;
    this.namespace = ns;
    this.decayFactor = parseDecayFactor(ns, conf);
    this.decayPeriodMillis = parseDecayPeriodMillis(ns, conf);
    this.identityProvider = this.parseIdentityProvider(ns, conf);
    this.costProvider = this.parseCostProvider(ns, conf);
    this.thresholds = parseThresholds(ns, conf, numLevels);
    this.backOffByResponseTimeEnabled = parseBackOffByResponseTimeEnabled(ns,
        conf);
    this.backOffResponseTimeThresholds =
        parseBackOffResponseTimeThreshold(ns, conf, numLevels);
    this.serviceUserNames = this.parseServiceUserNames(ns, conf);

    // Setup response time metrics
    responseTimeTotalInCurrWindow = new AtomicLongArray(numLevels);
    responseTimeCountInCurrWindow = new AtomicLongArray(numLevels);

View on GitHub (pinned to 2add963021)

Solutions

1. Set ipc.<port>.callqueue-priority-levels to a value >= 1 (1 disables prioritization effectively) in the server config and restart.
2. If you construct DecayRpcScheduler yourself, validate numLevels >= 1 before the call.
3. Remove the key entirely to fall back to the default level count if you did not intend to tune it.

Example fix

// before (core-site.xml on the server)
<property><name>ipc.8020.callqueue-priority-levels</name><value>0</value></property>
<!-- DecayRpcScheduler ctor throws IllegalArgumentException -->

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

// server startup, before constructing the scheduler
int levels = conf.getInt("ipc." + port + ".callqueue-priority-levels", 1);
if (levels < 1) {
  throw new ConfigException("ipc." + port + ".callqueue-priority-levels must be >= 1, got " + levels);
}

When it happens

Trigger: Setting ipc.<port>.callqueue-priority-levels to 0 or a negative number in the server's Configuration; constructing DecayRpcScheduler directly (e.g., in tests or custom schedulers) with numLevels < 1; a parsing bug computing levels from a property that defaults to 0.

Common situations: Hardening/tuning attempts that disable priority queues by setting the level count to 0; copy-pasted XML with a typo (level=0 instead of 1); unit tests instantiating the scheduler with edge-case arguments.

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

• Decay Factor must be between 0 and 1
• Period millis must be >= 0
• Number of Priority Levels must be at least 1
• Number of thresholds should be {}. Was: {}
• responseTimeThresholds must match with the number of priorit

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