apache/pulsar · error · AuthenticationException

INVALID_HEADER

INVALID_HEADER

Error message

Authentication token has to be started with "Basic "

What it means

Header-format guard in the inner AuthParams parser of AuthenticationProviderBasic: the Authorization header value is blank or does not begin with the "Basic " scheme prefix, so no Base64 user:password payload can be extracted; a malformed or wrong-scheme Authorization header is the faulty input.

Source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderBasic.java:174

        }
        authenticationMetrics.recordSuccess();
        return userId;
    }

    private class AuthParams {
        private String userId;
        private String password;

        public AuthParams(AuthenticationDataSource authData) throws AuthenticationException {
            String authParams;
            if (authData.hasDataFromCommand()) {
                authParams = authData.getCommandData();
            } else if (authData.hasDataFromHttp()) {
                String rawAuthToken = authData.getHttpHeader(HTTP_HEADER_NAME);
                // parsing and validation
                if (StringUtils.isBlank(rawAuthToken) || !rawAuthToken.toUpperCase().startsWith("BASIC ")) {
                    incrementFailureMetric(ErrorCode.INVALID_HEADER);
                    throw new AuthenticationException("Authentication token has to be started with \"Basic \"");
                }
                String[] splitRawAuthToken = rawAuthToken.split(" ");
                if (splitRawAuthToken.length != 2) {
                    incrementFailureMetric(ErrorCode.INVALID_HEADER);
                    throw new AuthenticationException("Base64 encoded token is not found");
                }

                try {
                    authParams = new String(Base64.getDecoder().decode(splitRawAuthToken[1]));
                } catch (Exception e) {
                    incrementFailureMetric(ErrorCode.INVALID_HEADER);
                    throw new AuthenticationException("Base64 decoding is failure: " + e.getMessage());
                }
            } else {
                incrementFailureMetric(ErrorCode.EMPTY_AUTH_DATA);
                throw new AuthenticationException("Authentication data source does not have data");
            }

View on GitHub (pinned to 820761864e)

Solutions

1. Send the header as 'Basic <base64(user:password)>'

When it happens

Trigger: Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderBasic.java:174 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

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

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