{"record":{"id":"0d8467650869c0c0","repo":"apache/hadoop","slug":"numlevels-must-be-at-least-1","errorCode":null,"errorMessage":"numLevels must be at least 1","messagePattern":"numLevels must be at least 1","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"critical","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/CallQueueManager.java","lineNumber":408,"sourceCode":"   */\n  @SuppressWarnings(\"deprecation\")\n  private static int parseNumLevels(String ns, Configuration conf) {\n    // Fair call queue levels (IPC_CALLQUEUE_PRIORITY_LEVELS_KEY)\n    // takes priority over the scheduler level key\n    // (IPC_SCHEDULER_PRIORITY_LEVELS_KEY)\n    int retval = conf.getInt(ns + \".\" +\n        FairCallQueue.IPC_CALLQUEUE_PRIORITY_LEVELS_KEY, 0);\n    if (retval == 0) { // No FCQ priority level configured\n      retval = conf.getInt(ns + \".\" +\n          CommonConfigurationKeys.IPC_SCHEDULER_PRIORITY_LEVELS_KEY,\n          CommonConfigurationKeys.IPC_SCHEDULER_PRIORITY_LEVELS_DEFAULT_KEY);\n    } else {\n      LOG.warn(ns + \".\" + FairCallQueue.IPC_CALLQUEUE_PRIORITY_LEVELS_KEY +\n          \" is deprecated. Please use \" + ns + \".\" +\n          CommonConfigurationKeys.IPC_SCHEDULER_PRIORITY_LEVELS_KEY + \".\");\n    }\n    if(retval < 1) {\n      throw new IllegalArgumentException(\"numLevels must be at least 1\");\n    }\n    return retval;\n  }\n\n  /**\n   * Read the weights of capacity in callqueue and pass the value to\n   * callqueue constructions.\n   */\n  private static int[] parseCapacityWeights(\n      int priorityLevels, String ns, Configuration conf) {\n    int[] weights = conf.getInts(ns + \".\" +\n      CommonConfigurationKeys.IPC_CALLQUEUE_CAPACITY_WEIGHTS_KEY);\n    if (weights.length == 0) {\n      weights = getDefaultQueueCapacityWeights(priorityLevels);\n    } else if (weights.length != priorityLevels) {\n      throw new IllegalArgumentException(\n          CommonConfigurationKeys.IPC_CALLQUEUE_CAPACITY_WEIGHTS_KEY + \" must \"\n              + \"specify \" + priorityLevels + \" capacity weights: one for each \"","sourceCodeStart":390,"sourceCodeEnd":426,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/ipc/CallQueueManager.java#L390-L426","documentation":"CallQueueManager.parsePriorityLevels resolves the number of priority levels for the call queue: it first reads the deprecated ipc.<port>.callqueue.priority.levels, then ipc.<port>.scheduler.priority.levels (default 4). It throws IllegalArgumentException(\"numLevels must be at least 1\") when the resolved value is < 1, which aborts RPC server startup.","triggerScenarios":"Explicitly setting ipc.<port>.scheduler.priority.levels (or the deprecated ipc.<port>.callqueue.priority.levels) to 0 or a negative number in core-site.xml / programmatic Configuration; a typo like 'priority.levels=-1' or a property placeholder resolving to 0.","commonSituations":"Operators trying to disable FairCallQueue tiering by setting levels to 0 (not supported — 1 is the minimum, meaning a single level); configuration management (Ansible/Cloudera templates) defaulting the key to 0; upgrading configs that carried the deprecated key with a bad value (which also logs a deprecation warning).","solutions":["Set ipc.<port>.scheduler.priority.levels to 1 for a single-level queue, or >= 2 for tiered scheduling.","Remove the deprecated ipc.<port>.callqueue.priority.levels key entirely — a stale 0 there takes precedence and triggers this too.","Search the effective config (hadoop conf -source or 'hdfs getconf -confKey') for priority.levels overrides you forgot about.","After fixing, restart the RPC server and confirm startup succeeds."],"exampleFix":"# before\n<property><name>ipc.8020.scheduler.priority.levels</name><value>0</value></property>\n\n# after\n<property><name>ipc.8020.scheduler.priority.levels</name><value>1</value></property>","handlingStrategy":"validation","validationCode":"int levels = conf.getInt(\"ipc.8020.scheduler.priority.levels\", 4);\nif (conf.get(\"ipc.8020.callqueue.priority.levels\") != null) {\n  LOG.warn(\"deprecated key set; value=\" + conf.getInt(\"ipc.8020.callqueue.priority.levels\", 0));\n}\nPreconditions.checkArgument(levels >= 1, \"scheduler.priority.levels must be >= 1\");","typeGuard":null,"tryCatchPattern":"try {\n  int levels = parsePriorityLevels(conf);\n} catch (IllegalArgumentException e) {\n  // config is bad; fail deployment loudly rather than retrying\n}","preventionTips":["Use 1 (single level) as the minimum, never 0, when you want a simple queue.","Delete the deprecated callqueue.priority.levels key from all configs.","Add a config lint step for ipc.<port>.* keys before rolling out."],"tags":["hadoop","ipc","configuration","callqueue","validation","server-startup"],"backgroundTag":"invalid-configuration-value","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}