{"record":{"id":"742092cff57cdebc","repo":"apache/hadoop","slug":"unable-to-refresh-queues-because-queue-hierarchy-c","errorCode":null,"errorMessage":"Unable to refresh queues because queue-hierarchy changed. Retaining existing configuration. ","messagePattern":"Unable to refresh queues because queue-hierarchy changed\\. Retaining existing configuration\\. ","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapred/QueueManager.java","lineNumber":353,"sourceCode":"   * @throws IOException when queue configuration file is invalid.\n   */\n  synchronized void refreshQueues(Configuration conf,\n      QueueRefresher schedulerRefresher)\n      throws IOException {\n\n    // Create a new configuration parser using the passed conf object.\n    QueueConfigurationParser cp =\n        getQueueConfigurationParser(conf, true, areAclsEnabled);\n\n    /*\n     * (1) Validate the refresh of properties owned by QueueManager. As of now,\n     * while refreshing queue properties, we only check that the hierarchy is\n     * the same w.r.t queue names, ACLs and state for each queue and don't\n     * support adding new queues or removing old queues\n     */\n    if (!root.isHierarchySameAs(cp.getRoot())) {\n      LOG.warn(MSG_REFRESH_FAILURE_WITH_CHANGE_OF_HIERARCHY);\n      throw new IOException(MSG_REFRESH_FAILURE_WITH_CHANGE_OF_HIERARCHY);\n    }\n\n    /*\n     * (2) QueueManager owned properties are validated. Now validate and\n     * refresh the properties of scheduler in a single step.\n     */\n    if (schedulerRefresher != null) {\n      try {\n        schedulerRefresher.refreshQueues(cp.getRoot().getJobQueueInfo().getChildren());\n      } catch (Throwable e) {\n        StringBuilder msg =\n            new StringBuilder(\n                \"Scheduler's refresh-queues failed with the exception : \"\n                    + StringUtils.stringifyException(e));\n        msg.append(\"\\n\");\n        msg.append(MSG_REFRESH_FAILURE_WITH_SCHEDULER_FAILURE);\n        LOG.error(msg.toString());\n        throw new IOException(msg.toString());","sourceCodeStart":335,"sourceCodeEnd":371,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-mapreduce-project/hadoop-mapreduce-client/hadoop-mapreduce-client-core/src/main/java/org/apache/hadoop/mapred/QueueManager.java#L335-L371","documentation":"QueueManager.refreshQueues() (the target of 'mr admin -refresh-queues') only supports changing queue properties such as ACLs, state, and scheduler settings. It first checks root.isHierarchySameAs(): the new mapred-queues.xml must describe exactly the same queue names in the same parent-child structure. If any queue was added, removed, or renamed, this IOException is thrown and the previously loaded configuration stays active.","triggerScenarios":"Editing mapred-queues.xml to add a queue, delete a queue, rename one, or reparent children, then running refresh-queues or calling QueueManager.refreshQueues(newConfiguration).","commonSituations":"Operators try to onboard a new tenant queue without a restart; a queue is retired while jobs still reference it; config drift between nodes causes one node's copy of mapred-queues.xml to differ.","solutions":["Restore the queue names and hierarchy to match the running configuration (only ACL/state/scheduler property values may differ), then run refresh again.","To genuinely add or remove queues, plan a JobTracker restart instead of a refresh.","Diff the new mapred-queues.xml against the last-known-good copy tree-by-tree before deploying it.","Confirm all nodes see the same file so refreshes from different hosts agree."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// before refresh: compare queue name trees of running config vs new file\nSet<String> running = queueNamesAsPaths(qm.getQueueInfo().getChildren()); // e.g. \"root.eng.etl\"\nQueueConfigurationParser cp = QueueConfigurationParser.parse(\"mapred-queues.xml.new\");\nSet<String> candidate = queueNamesAsPaths(cp.getRoot().getJobQueueInfo().getChildren());\nif (!running.equals(candidate)) {\n  throw new IOException(\"Hierarchy differs: only property updates allowed; added=\"\n      + Sets.difference(candidate, running) + \" removed=\" + Sets.difference(running, candidate));\n}","typeGuard":null,"tryCatchPattern":"try {\n  queueManager.refreshQueues(conf);\n} catch (IOException e) {\n  if (e.getMessage().contains(\"queue-hierarchy changed\")) {\n    // refresh rejected; running config retained — either revert the file or plan a restart\n  }\n}","preventionTips":["Treat refresh-queues as property-only; queue topology changes require a JobTracker restart.","Keep the deployed mapred-queues.xml in version control and diff trees before refresh.","Never rely on refresh to add or remove queues for new tenants."],"tags":["hadoop","mapreduce","queues","refresh","admin","config"],"backgroundTag":"hot-reload-requires-restart","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}