apache/pulsar · error · AuthenticationException

Authentication required

Error message

Authentication required

What it means

In the servlet-based authenticateHttpRequest, when the request carries no auth method header, no provider successfully authenticated it, and no anonymousUserRole is configured, the broker rejects the request with AuthenticationException('Authentication required'). At least one provider is configured (authentication is enabled), so unauthenticated requests are not permitted.

Source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationService.java:163

                throw new AuthenticationException("Authentication method missing");
            }
            for (AuthenticationProvider provider : providers.values()) {
                try {
                    return provider.authenticateHttpRequest(request, response);
                } catch (Exception e) {
                    log.debug().exception(e).log("Authentication failed for provider :");
                    // Ignore the exception because we don't know which authentication method is expected here.
                }
            }
            // No authentication provided
            if (!providers.isEmpty()) {
                if (StringUtils.isNotBlank(anonymousUserRole)) {
                    request.setAttribute(AuthenticatedRoleAttributeName, anonymousUserRole);
                    request.setAttribute(AuthenticatedDataAttributeName, new AuthenticationDataHttps(request));
                    return true;
                }
                // If at least a provider was configured, then the authentication needs to be provider
                throw new AuthenticationException("Authentication required");
            } else {
                // No authentication required
                return true;
            }
        }
    }

    /**
     * @deprecated use {@link #authenticateHttpRequest(HttpServletRequest, HttpServletResponse)}
     */
    @Deprecated(since = "3.0.0")
    public String authenticateHttpRequest(HttpServletRequest request, AuthenticationDataSource authData)
            throws AuthenticationException {
        String authMethodName = getAuthMethodName(request);

        if (authMethodName != null) {
            AuthenticationProvider providerToUse = getAuthProvider(authMethodName);
            try {

View on GitHub (pinned to 820761864e)

Solutions

1. Send valid credentials (e.g. Authorization: Bearer <token> with Pulsar-Auth-Method-Name: token)
2. Set anonymousUserRole in broker.conf to allow unauthenticated requests under a fixed role
3. Verify the client's credential format matches one of the configured providers
4. Check broker logs (debug level) for which providers rejected the credentials to fix the credential itself

Example fix

// before (broker.conf): authentication enabled, no anonymous fallback
// curl http://broker:8080/admin/v2/clusters -> Authentication required
// after: allow anonymous or authenticate
curl -H "Pulsar-Auth-Method-Name: token" -H "Authorization: Bearer eyJ..." http://broker:8080/admin/v2/clusters
// or: anonymousUserRole=anonymous

// client-side precheck: ensure credentials exist before calling
if (authToken == null || authToken.isBlank()) {
    throw new IllegalStateException("Refusing unauthenticated call to an auth-enabled broker");
}

try {
    authenticated = authService.authenticateHttpRequest(request, response);
} catch (javax.naming.AuthenticationException e) {
    if ("Authentication required".equals(e.getMessage())) {
        response.sendError(401, "Credentials required");
    }
}

When it happens

Trigger: Request with no Pulsar-Auth-Method-Name header; every configured provider's authenticateHttpRequest fails or returns false (e.g. missing/invalid Authorization header); strictAuthMethod=false; anonymousUserRole is blank/unset.

Common situations: Client simply omits credentials against an auth-enabled broker; client sends credentials in a format no configured provider accepts; token expired so the token provider rejects it and no anonymous fallback exists; anonymousUserRole not set though operators expected open anonymous access.

Understand the failure class

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

Related errors

• Unsupported authentication method: [${authMethodName}].
• Authentication method missing
• Invalid combination of Original principal cannot be empty if
• Need to authenticate to perform the request
• Failed to authentication http request

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