apache/pulsar · error · RestException

This operation requires super-user access

Error message

This operation requires super-user access

What it means

validateSuperUserAccess checks the authenticated appId against config.getSuperUserRoles(); if the role is not listed it throws RestException(UNAUTHORIZED, 'This operation requires super-user access'). Called for admin operations (and via validateUserAccess) on the websocket proxy's REST endpoints.

Source

Thrown at pulsar-websocket/src/main/java/org/apache/pulsar/websocket/admin/WebSocketWebResource.java:116

        return authenticationDataSource;
    }

    /**
     * Checks whether the user has Pulsar Super-User access to the system.
     *
     * @throws RestException
     *             if not authorized
     */
    protected void validateSuperUserAccess() {
        if (service().getConfig().isAuthenticationEnabled()) {
            String appId = clientAppId();
            log.debug()
                    .attr("requestUri", uri.getRequestUri())
                    .attr("authenticated", clientAppId())
                    .attr("role", appId)
                    .log("Check super user access: Authenticated: -- Role");
            if (!service().getConfig().getSuperUserRoles().contains(appId)) {
                throw new RestException(Status.UNAUTHORIZED, "This operation requires super-user access");
            }
        }
    }

    /**
     * Checks if user has super-user access or user is authorized to produce/consume on a given topic.
     *
     * @param topic
     * @throws RestException
     */
    protected void validateUserAccess(TopicName topic) {
        boolean isAuthorized = false;

        try {
            validateSuperUserAccess();
            isAuthorized = true;
        } catch (Exception e) {
            try {

View on GitHub (pinned to 820761864e)

Solutions

1. Add the authenticated role to superUserRoles in the websocket proxy configuration and restart
2. Verify the exact role string from the token (use the logs' 'role' attribute) matches the configured entry exactly
3. Use a role that already has super-user access for admin operations
4. If the operation should only need topic-level authorization, call a non-superuser endpoint instead

Example fix

// before
superUserRoles=[]
// after
superUserRoles=[admin]

// client-side pre-check
Set<String> myRoles = tokenRoles(jwt); if (!myRoles.contains("admin")) { throw new SecurityException("operation requires a super-user role"); }

boolean isSuperUser(String role, WebSocketProxyConfiguration c) { return role != null && c.getSuperUserRoles().contains(role); }

try { return webResource.adminOp(); } catch (WebApplicationException e) { if (e.getResponse().getStatus() == 401 && e.getMessage().contains("super-user")) { throw new AccessDeniedException("use a super-user role for this operation"); } throw e; }

When it happens

Trigger: A non-superuser role calls an admin endpoint requiring super-user privileges, e.g. proxy stats or access validation paths that first check validateSuperUserAccess.

Common situations: Role authenticated fine but simply absent from superUserRoles; superUserRoles configured on the broker but not on the websocket proxy config; role string mismatch (case, prefix) between token subject and configured role.

Understand the failure class

Background: "You do not have permission" / 403 Forbidden errors: authenticated but not allowed — causes and fixes across open-source libraries — this error's family across 31 libraries.

Related errors

• Don't have permission to connect to this namespace
• Tenant does not exist
• This operation requires super-user access
• Client is not authorized to perform operation
• Invalid broker configuration. Authentication must be enabled

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