apache/hadoop · error · AccessControlException

Access denied for user {}. Superuser privilege is required f

Error message

Access denied for user {}. Superuser privilege is required for operation {}

What it means

The default INodeAttributeProvider.AccessControlEnforcer.checkSuperUserPermissionWithContext throws AccessControlException when the caller's short username is not the NameNode start user (fsOwner) AND the caller's groups do not contain the supergroup. This default is the superuser gate used (among others) by HDFS Router admin paths when no custom provider overrides it; the message names the denied user and the operation that required privilege.

Source

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

    /**
     * Checks if the user is a superuser or belongs to superuser group.
     * It throws an AccessControlException if user is not a superuser.
     *
     * @param authzContext an {@link AuthorizationContext} object encapsulating
     *                     the various parameters required to authorize an
     *                     operation.
     * @throws AccessControlException - if user is not a super user or part
     * of the super user group.
     */
    default void checkSuperUserPermissionWithContext(
        AuthorizationContext authzContext)
        throws AccessControlException {
      UserGroupInformation callerUgi = authzContext.getCallerUgi();
      boolean isSuperUser =
          callerUgi.getShortUserName().equals(authzContext.getFsOwner()) ||
          callerUgi.getGroupsSet().contains(authzContext.getSupergroup());
      if (!isSuperUser) {
        throw new AccessControlException("Access denied for user " +
            callerUgi.getShortUserName() + ". Superuser privilege is " +
            "required for operation " + authzContext.getOperationName());
      }
    }

    /**
     * This method must be called when denying access to users to
     * notify the external enforcers.
     * This will help the external enforcers to audit the requests
     * by users that were denied access.
     * @param authzContext an {@link AuthorizationContext} object encapsulating
     *                     the various parameters required to authorize an
     *                     operation.
     * @throws AccessControlException
     */
    default void denyUserAccess(AuthorizationContext authzContext,
                                String errorMessage)
        throws AccessControlException {

View on GitHub (pinned to 2add963021)

Solutions

Run the operation as the NameNode start user (typically 'hdfs') via sudo -u hdfs or kinit as the NN principal
Add the caller to the group configured in dfs.permissions.supergroup (verify with `id <user>`) and retry
If a custom authz provider should govern this check, override checkSuperUserPermissionWithContext instead of relying on the default

Example fix

# before
kinit opsuser@REALM
hdfs dfsadmin -refreshNodes   # opsuser is not fsOwner/supergroup -> denied

# after
sudo -u hdfs hdfs dfsadmin -refreshNodes
# or: usermod -aG supergroup opsuser && re-login && retry

Defensive patterns

Strategy: validation

Validate before calling

// Verify superuser privilege before invoking a superuser-gated admin op
UserGroupInformation ugi = UserGroupInformation.getCurrentUser();
boolean isSuper = ugi.getShortUserName().equals(fsOwner)
    || ugi.getGroupsSet().contains(supergroup);   // e.g. from dfs.permissions.supergroup
if (!isSuper) {
  throw new AccessControlException("Run as " + fsOwner
      + " or a member of " + supergroup);
}

Try / catch

catch (AccessControlException e) {
  if (e.getMessage() != null && e.getMessage().contains("Superuser privilege is required")) {
    // privilege problem — escalate/reauthenticate as fsOwner or supergroup member; do not retry as-is
    throw new SecurityException("Re-run as the NameNode user or add caller to "
        + "dfs.permissions.supergroup", e);
  }
  throw e;
}

Prevention

Centralize admin operations in a wrapper that kinit/sudo's as the NameNode start user
Keep an explicit mapping of service accounts to dfs.permissions.supergroup membership
Verify group resolution (id <user>) on the gateway host — NSS/LDAP hiccups silently drop supergroup membership

When it happens

Trigger: Invoking an admin operation that routes through checkSuperUserPermissionWithContext (Router-based federation admin APIs, superuser-gated refresh ops) as a user who is neither the NN start user nor in dfs.permissions.supergroup; Kerberos principal mismatch between caller and fsOwner.

Common situations: Running admin commands from a service account that was never granted the supergroup; supergroup left at default 'supergroup' with no members added; after changing dfs.permissions.supergroup without restarting or re-issuing group membership.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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