apache/pulsar · error · RestException

This operation requires super-user access

Error message

This operation requires super-user access

What it means

When the authenticated appId is NOT a proxy role, validateSuperUserAccessAsync performs a single isSuperUser(appId) check; if it returns false the admin call is rejected with HTTP 401 'This operation requires super-user access'. This guards super-user-only REST operations.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/web/PulsarWebResource.java:261

                                .isSuperUser(originalPrincipal, clientAuthData());
                    }).thenAccept(originalPrincipalAuthorizationSuccess -> {
                        if (!originalPrincipalAuthorizationSuccess){
                            throw new RestException(Status.UNAUTHORIZED,
                                    String.format("Original principal not authorized for super-user operation "
                                                    + "(original:%s)", originalPrincipal));
                        }
                            log.debug()
                                    .attr("authorized", originalPrincipal)
                                    .attr("proxyAppId", appId)
                                    .log("Successfully authorized as super-user");
                                            });
        } else {
            return pulsar.getBrokerService()
                    .getAuthorizationService()
                    .isSuperUser(appId, clientAuthData())
                    .thenAccept(proxyAuthorizationSuccess -> {
                        if (!proxyAuthorizationSuccess) {
                            throw new RestException(Status.UNAUTHORIZED,
                                    "This operation requires super-user access");
                        }
                    });
        }
    }

    /**
     * Checks whether the user has Pulsar Super-User access to the system.
     *
     * @throws WebApplicationException
     *             if not authorized
     */
    public void validateSuperUserAccess() {
        sync(this::validateSuperUserAccessAsync);
    }

    /**
     * Checks that the http client role has admin access to the specified tenant.

View on GitHub (pinned to 820761864e)

Solutions

1. Add the client's role to superUserRoles in broker.conf (or via your AuthorizationProvider)
2. Decode the client's credential/token to confirm which role is actually authenticated
3. Downgrade the operation to a tenant/namespace-scoped API that matches the client's permissions
4. Restart or wait for config reload after changing superUserRoles

Example fix

// before (broker.conf)
superUserRoles=[admin]
// after
superUserRoles=[admin,monitoring-client]

try {
    admin.clusters().getClusters();
} catch (PulsarAdminException e) {
    if (e.getStatusCode() == 401 && e.getMessage().contains("requires super-user access")) {
        // add the authenticated role to superUserRoles or use a scoped API
    }
    throw e;
}

When it happens

Trigger: Any non-proxy client calling a super-user-only admin endpoint (e.g. cluster/tenant management requiring super-user) without being listed in superUserRoles or granted super-user by the AuthorizationProvider.

Common situations: New admin clients onboarded without updating superUserRoles; authorization provider (e.g. custom or external store) lacking the role; token authenticating a different role than expected (audience/subject mismatch).

Related errors

• Proxy not authorized for super-user operation (proxy:%s)
• Original principal not authorized for super-user operation (
• Unauthorized to validateBothSuperuserAndBrokerOperation for
• Time-out while checking authorization
• Failed to get permissions

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/1f7ba985bc3b467d. Report an issue: GitHub.