{"record":{"id":"0893c1b2647ea60a","repo":"apache/hadoop","slug":"number-of-priority-levels-must-be-at-least-1","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/DecayRpcScheduler.java","lineNumber":238,"sourceCode":"      } else {\n        // Our scheduler was garbage collected since it is no longer in use,\n        // so we should terminate the timer as well\n        timer.cancel();\n        timer.purge();\n      }\n    }\n  }\n\n  /**\n   * Create a decay scheduler.\n   * @param numLevels number of priority levels\n   * @param ns config prefix, so that we can configure multiple schedulers\n   *           in a single instance.\n   * @param conf configuration to use.\n   */\n  public DecayRpcScheduler(int numLevels, String ns, Configuration conf) {\n    if(numLevels < 1) {\n      throw new IllegalArgumentException(\"Number of Priority Levels must be \" +\n          \"at least 1\");\n    }\n    this.numLevels = numLevels;\n    this.namespace = ns;\n    this.decayFactor = parseDecayFactor(ns, conf);\n    this.decayPeriodMillis = parseDecayPeriodMillis(ns, conf);\n    this.identityProvider = this.parseIdentityProvider(ns, conf);\n    this.costProvider = this.parseCostProvider(ns, conf);\n    this.thresholds = parseThresholds(ns, conf, numLevels);\n    this.backOffByResponseTimeEnabled = parseBackOffByResponseTimeEnabled(ns,\n        conf);\n    this.backOffResponseTimeThresholds =\n        parseBackOffResponseTimeThreshold(ns, conf, numLevels);\n    this.serviceUserNames = this.parseServiceUserNames(ns, conf);\n\n    // Setup response time metrics\n    responseTimeTotalInCurrWindow = new AtomicLongArray(numLevels);\n    responseTimeCountInCurrWindow = new AtomicLongArray(numLevels);","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/DecayRpcScheduler.java#L220-L256","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set ipc.<port>.callqueue-priority-levels to a value >= 1 (1 disables prioritization effectively) in the server config and restart.","If you construct DecayRpcScheduler yourself, validate numLevels >= 1 before the call.","Remove the key entirely to fall back to the default level count if you did not intend to tune it."],"exampleFix":"// before (core-site.xml on the server)\n<property><name>ipc.8020.callqueue-priority-levels</name><value>0</value></property>\n<!-- DecayRpcScheduler ctor throws IllegalArgumentException -->\n\n// after\n<property><name>ipc.8020.callqueue-priority-levels</name><value>4</value></property>","handlingStrategy":"validation","validationCode":"// server startup, before constructing the scheduler\nint levels = conf.getInt(\"ipc.\" + port + \".callqueue-priority-levels\", 1);\nif (levels < 1) {\n  throw new ConfigException(\"ipc.\" + port + \".callqueue-priority-levels must be >= 1, got \" + levels);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate callqueue-related keys in a config pre-check (ConfigValidation) before daemon start.","Keep ipc.<port>.callqueue-priority-levels >= 1 and in sync with decay-scheduler.thresholds (levels - 1 entries).","Unit-test config permutations against DecayRpcScheduler/FairCallQueue construction in CI."],"tags":["hadoop","ipc","decay-scheduler","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"}