apache/pulsar · error · AuthenticationException

Failed to authentication http request

Error message

Failed to authentication http request

What it means

AuthenticationProvider.authenticateHttpRequest wraps synchronous authentication of an HTTP request. AuthenticationException is rethrown as-is, but any other exception (including ExecutionException from the async path whose cause is not an AuthenticationException, NPEs, misconfigured providers) is masked and rethrown as a generic AuthenticationException "Failed to authentication http request".

Source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProvider.java:202

     * @return Set response, according to passed in request, and return whether we should do following chain.doFilter.
     * @throws Exception when authentication failed
     * @deprecated use and implement {@link AuthenticationProvider#authenticateHttpRequestAsync} instead.
     */
    @Deprecated
    default boolean authenticateHttpRequest(HttpServletRequest request, HttpServletResponse response) throws Exception {
        try {
            AuthenticationState authenticationState = newHttpAuthState(request);
            String role = authenticateAsync(authenticationState.getAuthDataSource()).get();
            request.setAttribute(AuthenticatedRoleAttributeName, role);
            request.setAttribute(AuthenticatedDataAttributeName, authenticationState.getAuthDataSource());
            return true;
        } catch (AuthenticationException e) {
            throw e;
        } catch (Exception e) {
            if (e instanceof ExecutionException && e.getCause() instanceof AuthenticationException) {
                throw (AuthenticationException) e.getCause();
            } else {
                throw new AuthenticationException("Failed to authentication http request");
            }
        }
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Check broker log for the suppressed cause — enable DEBUG logging on AuthenticationProvider
2. Fix the provider configuration (e.g. provide the token secret key) or the malformed request header
3. In custom providers, catch and convert expected failures to AuthenticationException so the real cause surfaces

Example fix

// before (custom provider)
public User authenticate(AuthDataSource ds, String header) {
    return parse(header.split(" ")[1]); // NPE on malformed header
}
// after
public User authenticate(AuthenticationDataSource ds, String header) throws AuthenticationException {
    if (header == null || !header.startsWith("Bearer ")) throw new AuthenticationException("missing token");
    try { return parse(header.substring(7)); }
    catch (Exception e) { throw new AuthenticationException("bad token", e); }
}

try {
    String role = provider.authenticateHttpRequest(request);
} catch (AuthenticationException e) {
    respond(Response.status(UNAUTHORIZED).build());
}

When it happens

Trigger: authenticateHttpRequest()/authenticateHttpRequestAsync() encounters a non-auth exception: provider misconfigured, null auth header causing NPE, wrapped ExecutionException from the CompletableFuture, or RuntimeException inside a provider's authenticate().

Common situations: Missing authentication provider configuration (e.g. token provider without a secret key); broken interceptors/filters upstream; provider throwing unexpected exceptions on malformed headers.

Understand the failure class

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

Related errors

• Invalid HTTP Authorization header
• Unsupported authentication method: [${authMethodName}].
• Authentication method missing
• Authentication required
• Invalid broker configuration. Authentication must be enabled

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