apache/hadoop · error · AccessControlException

Manual HA control for this NameNode is disallowed, because a

Error message

Manual HA control for this NameNode is disallowed, because automatic HA is enabled.

What it means

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.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/NameNode.java:2308

    return this.started.get();
  }

  /**
   * Check that a request to change this node's HA state is valid.
   * In particular, verifies that, if auto failover is enabled, non-forced
   * requests from the HAAdmin CLI are rejected, and vice versa.
   *
   * @param req the request to check
   * @throws AccessControlException if the request is disallowed
   */
  void checkHaStateChange(StateChangeRequestInfo req)
      throws AccessControlException {
    boolean autoHaEnabled = getConf().getBoolean(
        DFS_HA_AUTO_FAILOVER_ENABLED_KEY, DFS_HA_AUTO_FAILOVER_ENABLED_DEFAULT);
    switch (req.getSource()) {
    case REQUEST_BY_USER:
      if (autoHaEnabled) {
        throw new AccessControlException(
            "Manual HA control for this NameNode is disallowed, because " +
            "automatic HA is enabled.");
      }
      break;
    case REQUEST_BY_USER_FORCED:
      if (autoHaEnabled) {
        LOG.warn("Allowing manual HA control from " +
            Server.getRemoteAddress() +
            " even though automatic HA is enabled, because the user " +
            "specified the force flag");
      }
      break;
    case REQUEST_BY_ZKFC:
      if (!autoHaEnabled) {
        throw new AccessControlException(
            "Request from ZK failover controller at " +
            Server.getRemoteAddress() + " denied since automatic HA " +
            "is not enabled"); 

View on GitHub (pinned to 2add963021)

Solutions

1. Use `hdfs haadmin -failover <activeId> <standbyId>` instead - it drives the failover through the ZKFCs and is the supported path under auto HA
2. If a manual transition is unavoidable, append `-forcemanual` to the transitionTo* command - the NameNode logs a warning (REQUEST_BY_USER_FORCED) and permits it
3. 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
4. Before any manual action, confirm ZKFC health and current states with `hdfs haadmin -getServiceState <nnId>`

Example fix

# before (rejected: REQUEST_BY_USER while auto HA enabled)
hdfs haadmin -transitionToStandby nn1

# after - coordinated failover via ZKFC
hdfs haadmin -failover nn1 nn2

# or, if manual control is truly required
hdfs haadmin -transitionToStandby nn1 -forcemanual

# Before issuing a manual transition, read the NN-side flag
if hdfs getconf -confKey dfs.ha.automatic-failover.enabled | grep -qi '^true'; then
  echo "auto HA enabled: use 'hdfs haadmin -failover' or add -forcemanual"
  exit 1
fi
hdfs haadmin -transitionToStandby nn1

try {
  proxy.transitionToStandby(reqInfo);
} catch (AccessControlException ace) {
  // manual control rejected because auto HA is on
  // fall back to HAAdmin failover via ZKFC, or retry with the force flag
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Request from ZK failover controller at {Server.getRemoteAddr
• {} is in observer state. Cannot be failover target
• Unexpected ZooKeeper issue fetching active node info
• The log file {} seems to contain valid transactions ; journa
• The journal edits cache is not enabled, which is a requireme

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