apache/hadoop · error · AccessControlException

Manual HA control for this NameNode is disallowed, because…

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.

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
• Block pool has not recognized an active NN
• Cannot open filename
• Cannot transition from 'active' to 'observer'
• Cannot transition from 'observer' to 'active'

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

Appendix: 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)