{"record":{"id":"b35e765012a1cf12","repo":"apache/pulsar","slug":"authentication-plugin-does-not-expose-binaryauthd","errorCode":null,"errorMessage":"authentication plugin  does not expose BinaryAuthDataProvider; the Pulsar binary transport requires it (PIP-478)","messagePattern":"authentication plugin  does not expose BinaryAuthDataProvider; the Pulsar binary transport requires it \\(PIP-478\\)","errorType":"exception","errorClass":"PulsarClientException.UnsupportedAuthenticationException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/PulsarClientImpl.java","lineNumber":479,"sourceCode":"     *\n     * <p>The binary transport requires {@code BinaryAuthDataProvider} (PIP-478 binary routing rule 1). Without\n     * this check the plugin builds fine and every connection attempt fails the same way for the client's\n     * lifetime, with the reason buried in a connection failure rather than stated where the mistake was made.\n     * Capabilities are only meaningful once the plugin has initialized, so the check follows initialization\n     * rather than preceding it.\n     */\n    private void requireUsableForBinaryTransport(org.apache.pulsar.client.api.v5.auth.Authentication v5,\n            V5BinaryAuthenticationDriver driver) throws PulsarClientException {\n        try {\n            driver.initializedAsync().get();\n        } catch (InterruptedException e) {\n            Thread.currentThread().interrupt();\n            throw new PulsarClientException(e);\n        } catch (Exception e) {\n            throw PulsarClientException.unwrap(e);\n        }\n        if (v5.capability(BinaryAuthDataProvider.class).isEmpty()) {\n            throw new PulsarClientException.UnsupportedAuthenticationException(\n                    \"authentication plugin \" + v5.getClass().getName() + \" does not expose \"\n                            + \"BinaryAuthDataProvider; the Pulsar binary transport requires it (PIP-478)\");\n        }\n    }\n\n    /**\n     * Resolve the client-side TLS SPI factory (PIP-478) and stash it on the configuration so the connection\n     * pool ({@code PulsarChannelInitializer}) and the HTTP lookup ({@code HttpClient}) build engines from it.\n     * This is the only client TLS path since the PIP-337 removal. It normally runs only when broker TLS is\n     * enabled (a plaintext client leaves {@code conf.getTlsFactory()} null, and its transports never request\n     * TLS); {@link #needsClientTlsFactory()} lists the two configurations that also need it on an otherwise\n     * plaintext client. On the v5-builder path a fail-fast probe of {@code CLIENT_DEFAULT} runs, so a\n     * bad configuration fails the client build.\n     *\n     * @throws PulsarClientException if the TLS factory cannot be built / initialized / probed\n     */\n    private void setupClientTlsFactory() throws PulsarClientException {\n        // Rebuildable (PIP-478) only when the framework composes the default file-based factory from the","sourceCodeStart":461,"sourceCodeEnd":497,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/PulsarClientImpl.java#L461-L497","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use an auth plugin that implements/exposes BinaryAuthDataProvider (e.g. the standard token/OAuth2 plugins).","Register the BinaryAuthDataProvider capability in a custom plugin, or fall back to the legacy org.apache.pulsar.client.api.Authentication plugin.","Wrap the v5 plugin with an adapter that provides BinaryAuthDataProvider."],"exampleFix":"// before\nconf.setAuthentication(new HttpOnlyV5AuthPlugin());\n// after\nconf.setAuthentication(new TokenAuthenticationProvider().withBinaryTransport()); // exposes BinaryAuthDataProvider","handlingStrategy":"validation","validationCode":"org.apache.pulsar.client.api.v5.auth.Authentication v5 = ...;\nif (v5.capability(BinaryAuthDataProvider.class).isEmpty()) {\n    throw new IllegalArgumentException(\"Auth plugin \" + v5.getClass().getName()\n        + \" lacks BinaryAuthDataProvider required for binary transport\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    client = PulsarClient.builder().authentication(v5Plugin).create();\n} catch (PulsarClientException.UnsupportedAuthenticationException e) {\n    // fall back to a plugin exposing BinaryAuthDataProvider\n    client = PulsarClient.builder().authentication(new TokenAuthenticationProvider())...create();\n}","preventionTips":["Verify your v5 auth plugin registers BinaryAuthDataProvider before using it with the binary protocol.","Prefer first-party plugins (token, OAuth2) that support PIP-478.","Pin plugin versions compatible with the client's auth API version."],"tags":["pulsar","authentication","binary-transport","unsupported-authentication"],"backgroundTag":"unsupported-authentication-plugin","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}