apache/pulsar · error · PulsarClientException.UnsupportedAuthenticationException

authentication plugin does not expose BinaryAuthDataProvide

Error message

authentication plugin  does not expose BinaryAuthDataProvider; the Pulsar binary transport requires it (PIP-478)

What it means

PIP-478 v5 authentication plugins must expose BinaryAuthDataProvider to work over Pulsar's binary transport. requireUsableForBinaryTransport checks v5.capability(BinaryAuthDataProvider.class); if empty, it throws UnsupportedAuthenticationException naming the plugin class that lacks the capability.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/PulsarClientImpl.java:479

     *
     * <p>The binary transport requires {@code BinaryAuthDataProvider} (PIP-478 binary routing rule 1). Without
     * this check the plugin builds fine and every connection attempt fails the same way for the client's
     * lifetime, with the reason buried in a connection failure rather than stated where the mistake was made.
     * Capabilities are only meaningful once the plugin has initialized, so the check follows initialization
     * rather than preceding it.
     */
    private void requireUsableForBinaryTransport(org.apache.pulsar.client.api.v5.auth.Authentication v5,
            V5BinaryAuthenticationDriver driver) throws PulsarClientException {
        try {
            driver.initializedAsync().get();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new PulsarClientException(e);
        } catch (Exception e) {
            throw PulsarClientException.unwrap(e);
        }
        if (v5.capability(BinaryAuthDataProvider.class).isEmpty()) {
            throw new PulsarClientException.UnsupportedAuthenticationException(
                    "authentication plugin " + v5.getClass().getName() + " does not expose "
                            + "BinaryAuthDataProvider; the Pulsar binary transport requires it (PIP-478)");
        }
    }

    /**
     * Resolve the client-side TLS SPI factory (PIP-478) and stash it on the configuration so the connection
     * pool ({@code PulsarChannelInitializer}) and the HTTP lookup ({@code HttpClient}) build engines from it.
     * This is the only client TLS path since the PIP-337 removal. It normally runs only when broker TLS is
     * enabled (a plaintext client leaves {@code conf.getTlsFactory()} null, and its transports never request
     * TLS); {@link #needsClientTlsFactory()} lists the two configurations that also need it on an otherwise
     * plaintext client. On the v5-builder path a fail-fast probe of {@code CLIENT_DEFAULT} runs, so a
     * bad configuration fails the client build.
     *
     * @throws PulsarClientException if the TLS factory cannot be built / initialized / probed
     */
    private void setupClientTlsFactory() throws PulsarClientException {
        // Rebuildable (PIP-478) only when the framework composes the default file-based factory from the

View on GitHub (pinned to 820761864e)

Solutions

1. Use an auth plugin that implements/exposes BinaryAuthDataProvider (e.g. the standard token/OAuth2 plugins).
2. Register the BinaryAuthDataProvider capability in a custom plugin, or fall back to the legacy org.apache.pulsar.client.api.Authentication plugin.
3. Wrap the v5 plugin with an adapter that provides BinaryAuthDataProvider.

Example fix

// before
conf.setAuthentication(new HttpOnlyV5AuthPlugin());
// after
conf.setAuthentication(new TokenAuthenticationProvider().withBinaryTransport()); // exposes BinaryAuthDataProvider

org.apache.pulsar.client.api.v5.auth.Authentication v5 = ...;
if (v5.capability(BinaryAuthDataProvider.class).isEmpty()) {
    throw new IllegalArgumentException("Auth plugin " + v5.getClass().getName()
        + " lacks BinaryAuthDataProvider required for binary transport");
}

try {
    client = PulsarClient.builder().authentication(v5Plugin).create();
} catch (PulsarClientException.UnsupportedAuthenticationException e) {
    // fall back to a plugin exposing BinaryAuthDataProvider
    client = PulsarClient.builder().authentication(new TokenAuthenticationProvider())...create();
}

When it happens

Trigger: Configuring a client with a v5 Authentication implementation that implements the v5 interface but not the BinaryAuthDataProvider capability, then constructing a PulsarClientImpl that uses the binary protocol.

Common situations: Using an HTTP-only or v5-only auth plugin with the native binary protocol; upgrading Pulsar clients to the v5 auth API while the chosen plugin predates PIP-478; custom in-house auth plugins missing the capability registration.

Understand the failure class

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

Related errors

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

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