{"record":{"id":"c86bbfdb66135c8a","repo":"apache/hadoop","slug":"manual-ha-control-for-this-namenode-is-disallowed","errorCode":null,"errorMessage":"Manual HA control for this NameNode is disallowed, because automatic HA is enabled.","messagePattern":"Manual HA control for this NameNode is disallowed, because automatic HA is enabled\\.","errorType":"exception","errorClass":"AccessControlException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NameNode.java","lineNumber":2308,"sourceCode":"    return this.started.get();\n  }\n\n  /**\n   * Check that a request to change this node's HA state is valid.\n   * In particular, verifies that, if auto failover is enabled, non-forced\n   * requests from the HAAdmin CLI are rejected, and vice versa.\n   *\n   * @param req the request to check\n   * @throws AccessControlException if the request is disallowed\n   */\n  void checkHaStateChange(StateChangeRequestInfo req)\n      throws AccessControlException {\n    boolean autoHaEnabled = getConf().getBoolean(\n        DFS_HA_AUTO_FAILOVER_ENABLED_KEY, DFS_HA_AUTO_FAILOVER_ENABLED_DEFAULT);\n    switch (req.getSource()) {\n    case REQUEST_BY_USER:\n      if (autoHaEnabled) {\n        throw new AccessControlException(\n            \"Manual HA control for this NameNode is disallowed, because \" +\n            \"automatic HA is enabled.\");\n      }\n      break;\n    case REQUEST_BY_USER_FORCED:\n      if (autoHaEnabled) {\n        LOG.warn(\"Allowing manual HA control from \" +\n            Server.getRemoteAddress() +\n            \" even though automatic HA is enabled, because the user \" +\n            \"specified the force flag\");\n      }\n      break;\n    case REQUEST_BY_ZKFC:\n      if (!autoHaEnabled) {\n        throw new AccessControlException(\n            \"Request from ZK failover controller at \" +\n            Server.getRemoteAddress() + \" denied since automatic HA \" +\n            \"is not enabled\"); ","sourceCodeStart":2290,"sourceCodeEnd":2326,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NameNode.java#L2290-L2326","documentation":"Thrown by NameNode.checkHaStateChange when a state-change request with source REQUEST_BY_USER arrives at a NameNode whose configuration has dfs.ha.automatic-failover.enabled=true. With automatic (ZKFC/ZooKeeper) failover, manual state transitions are rejected because they bypass ZooKeeper coordination and fencing and can cause split-brain. The flag is read from this NameNode's own HdfsConfiguration, so only this node's hdfs-site.xml matters for the decision.","triggerScenarios":"Running `hdfs haadmin -transitionToActive <nnId>` or `-transitionToStandby <nnId>` WITHOUT the -forcemanual flag while the NameNode runs with dfs.ha.automatic-failover.enabled=true. Equivalently, a programmatic HAServiceProtocol.transitionToActive/Standby call whose RequestSource is REQUEST_BY_USER.","commonSituations":"Operators keep running the pre-auto-HA manual failover playbook after enabling ZKFC; config drift where hdfs-site.xml enables auto failover but the runbook assumes manual control; legacy automation scripts that call transitionTo* directly.","solutions":["Use `hdfs haadmin -failover <activeId> <standbyId>` instead - it drives the failover through the ZKFCs and is the supported path under auto HA","If a manual transition is unavoidable, append `-forcemanual` to the transitionTo* command - the NameNode logs a warning (REQUEST_BY_USER_FORCED) and permits it","If the cluster is intended to be manually managed, set dfs.ha.automatic-failover.enabled=false in hdfs-site.xml on the NameNodes and restart the NameNodes and ZKFCs","Before any manual action, confirm ZKFC health and current states with `hdfs haadmin -getServiceState <nnId>`"],"exampleFix":"# before (rejected: REQUEST_BY_USER while auto HA enabled)\nhdfs haadmin -transitionToStandby nn1\n\n# after - coordinated failover via ZKFC\nhdfs haadmin -failover nn1 nn2\n\n# or, if manual control is truly required\nhdfs haadmin -transitionToStandby nn1 -forcemanual","handlingStrategy":"validation","validationCode":"# Before issuing a manual transition, read the NN-side flag\nif hdfs getconf -confKey dfs.ha.automatic-failover.enabled | grep -qi '^true'; then\n  echo \"auto HA enabled: use 'hdfs haadmin -failover' or add -forcemanual\"\n  exit 1\nfi\nhdfs haadmin -transitionToStandby nn1","typeGuard":null,"tryCatchPattern":"try {\n  proxy.transitionToStandby(reqInfo);\n} catch (AccessControlException ace) {\n  // manual control rejected because auto HA is on\n  // fall back to HAAdmin failover via ZKFC, or retry with the force flag\n}","preventionTips":["Standardize on `hdfs haadmin -failover` in all runbooks once ZKFC is enabled","Keep the auto-failover flag identical in hdfs-site.xml across all HA nodes and the ZKFC host","Make transitionTo* automation check dfs.ha.automatic-failover.enabled first and abort with guidance"],"tags":["hdfs","name-node","ha","haadmin","failover","access-control","zookeeper"],"backgroundTag":"ha-failover-access-denied","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}