apache/pulsar · error · RestException

This operation requires super-user access

Error message

This operation requires super-user access

What it means

reloadConnectors requires super-user privileges when authorization is enabled on the function worker. If the authenticated principal is not in the super-user roles list, the worker returns HTTP 401 Unauthorized with this message and does not reload connectors.

Source

Thrown at pulsar-functions/worker/src/main/java/org/apache/pulsar/functions/worker/rest/api/ComponentImpl.java:1087

    @Override
    public List<ConnectorDefinition> getListOfConnectors() {
        if (!isWorkerServiceAvailable()) {
            throwUnavailableException();
        }

        return this.worker().getConnectorsManager().getConnectorDefinitions();
    }

    @Override
    public void reloadConnectors(AuthenticationParameters authParams) {
        if (!isWorkerServiceAvailable()) {
            throwUnavailableException();
        }
        if (worker().getWorkerConfig().isAuthorizationEnabled()) {
            // Only superuser has permission to do this operation.
            if (!isSuperUser(authParams)) {
                throw new RestException(Status.UNAUTHORIZED, "This operation requires super-user access");
            }
        }
        try {
            this.worker().getConnectorsManager().reloadConnectors(worker().getWorkerConfig());
        } catch (IOException e) {
            throw new RestException(Status.INTERNAL_SERVER_ERROR, e.getMessage());
        }
    }

    @Override
    public String triggerFunction(final String tenant,
                                  final String namespace,
                                  final String functionName,
                                  final String input,
                                  final InputStream uploadedInputStream,
                                  final String topic,
                                  final AuthenticationParameters authParams) {

View on GitHub (pinned to 820761864e)

Solutions

1. Add the caller's role to superUserRoles in the worker config (workerConfig) and restart/reload the worker.
2. Re-authenticate with credentials for an existing super-user role (valid client token/certificate).
3. If authorization is intentionally disabled in your environment, confirm isAuthorizationEnabled=false so the check is skipped.
4. Verify which role the worker resolved by checking its auth logs before adjusting configs.

Example fix

// worker.conf before
authorizationEnabled=true
superUserRoles=admin-readonly
// after
authorizationEnabled=true
superUserRoles=admin-readonly,connector-ops

// Pre-check that the credential's role is a configured super-user
boolean isSuperUser = workerConf.getSuperUserRoles().contains(myRole) && workerConf.isAuthorizationEnabled() == false ||
                      workerConf.getSuperUserRoles().contains(myRole);

try { admin.connectors().reloadConnectors(); }
catch (PulsarAdminException e) {
  if (e.getResponseStatus() == 401)
    log.error("reloadConnectors requires super-user; role={} not in superUserRoles", myRole);
  else throw e;
}

When it happens

Trigger: POST /admin/v3/functions/connectors/reload (reloadConnectors) called with credentials whose role is not listed in workerConfig's superUserRoles while authorizationEnabled=true.

Common situations: Ops automation running with a regular admin/service account instead of a super-user role; superUserRoles misconfigured on the worker after a config change; missing/invalid auth token so the role resolves to an anonymous non-super-user.

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

• Client is not authorized to perform operation
• Unauthorized to validateClusterOperation for originalPrincip
• Unauthorized to validateClusterPolicyOperation for originalP
• Unauthorized to validateBothTenantOperationAndSuperUser for
• Time-out while checking authorization

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