apache/pulsar · error · AuthenticationException

Authentication method missing

Error message

Authentication method missing

What it means

When no 'Pulsar-Auth-Method-Name' header is present on the request and the broker is configured with strictAuthMethod=true, authenticateHttpRequest throws AuthenticationException('Authentication method missing') immediately. Strict mode requires clients to explicitly declare which authentication method they use; the broker will not try every configured provider.

Source

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

        if (authMethodName == null
                && SaslConstants.SASL_TYPE_VALUE.equalsIgnoreCase(request.getHeader(SaslConstants.SASL_HEADER_TYPE))) {
            // This edge case must be handled because the Pulsar SASL implementation does not add the
            // X-Pulsar-Auth-Method-Name header.
            authMethodName = SaslConstants.AUTH_METHOD_NAME;
        }
        if (authMethodName != null) {
            AuthenticationProvider providerToUse = getAuthProvider(authMethodName);
            try {
                return providerToUse.authenticateHttpRequest(request, response);
            } catch (Exception e) {
                log.debug().attr("authMethod", authMethodName).exception(e)
                        .log("Authentication failed for provider");
                throw e;
            }
        } else {
            if (strictAuthMethod) {
                log.debug("No authentication method provided while one was is required");
                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");

View on GitHub (pinned to 820761864e)

Solutions

1. Configure the client to send the Pulsar-Auth-Method-Name header and valid credentials for that method
2. Set strictAuthMethod=false in broker.conf to fall back to trying all configured providers for header-less requests
3. If the request should be anonymous, configure anonymousUserRole so unauthenticated requests get that role (requires strictAuthMethod=false)
4. For SASL, ensure the SASL header type header is present so the method name can be inferred

Example fix

// before (broker.conf)
strictAuthMethod=true
// client: curl http://broker:8080/admin/v2/clusters  -> Authentication method missing
// after: send auth headers
curl -H "Pulsar-Auth-Method-Name: token" -H "Authorization: Bearer <jwt>" http://broker:8080/admin/v2/clusters
// or relax: strictAuthMethod=false

try {
    authenticated = authService.authenticateHttpRequest(request, response);
} catch (javax.naming.AuthenticationException e) {
    if ("Authentication method missing".equals(e.getMessage())) {
        response.sendError(401, "Pulsar-Auth-Method-Name header required (strictAuthMethod=true)");
    }
}

When it happens

Trigger: HTTP request to a broker with authenticationEnabled=true and strictAuthMethod=true that lacks the Pulsar-Auth-Method-Name header (and is not a SASL request with the SASL header type); e.g. a plain unauthenticated client, curl without auth headers, or a client library too old to send the header.

Common situations: Operator enabled strictAuthMethod but legacy clients/proxies don't send the auth method header; health-check or monitoring probes hitting the admin API without credentials; curl/scripts testing the REST API without auth headers; SASL edge case header not set.

Understand the failure class

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

Related errors

• Unsupported authentication method: [${authMethodName}].
• Authentication required
• Invalid broker configuration. Authentication must be enabled
• Broker doesn't allow forced deletion of namespaces
• Local cluster is not part of replicate cluster list

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