apache/pulsar · error · RuntimeException

Failed to create authentication: ${message}

Error message

Failed to create authentication: ${message}

What it means

RuntimeException thrown by loadConf-driven authentication setup when the configured authentication plugin class cannot be instantiated or configured (UnsupportedAuthenticationException). loadConf applies configuration properties including authPluginClass/authParams; if the plugin class is unknown, not on the classpath, or rejects the parameters, the builder fails eagerly with this message.

Source

Thrown at pulsar-client-admin/src/main/java/org/apache/pulsar/client/admin/internal/PulsarAdminBuilderImpl.java:257

        conf.setAuthentication(AuthenticationFactory.create(authPluginClassName, authParamsString));
        return this;
    }

    private void setAuthenticationFromPropsIfAvailable(ClientConfigurationData clientConfig) {
        String authPluginClass = clientConfig.getAuthPluginClassName();
        String authParams = clientConfig.getAuthParams();
        Map<String, String> authParamMap = clientConfig.getAuthParamMap();
        if (StringUtils.isBlank(authPluginClass) || (StringUtils.isBlank(authParams) && authParamMap == null)) {
            return;
        }
        try {
            if (StringUtils.isNotBlank(authParams)) {
                authentication(authPluginClass, authParams);
            } else if (authParamMap != null) {
                authentication(authPluginClass, authParamMap);
            }
        } catch (UnsupportedAuthenticationException ex) {
            throw new RuntimeException("Failed to create authentication: " + ex.getMessage(), ex);
        }
    }

    @Override
    public PulsarAdminBuilder tlsKeyFilePath(String tlsKeyFilePath) {
        conf.setTlsKeyFilePath(tlsKeyFilePath);
        return this;
    }

    @Override
    public PulsarAdminBuilder tlsCertificateFilePath(String tlsCertificateFilePath) {
        conf.setTlsCertificateFilePath(tlsCertificateFilePath);
        return this;
    }

    @Override
    public PulsarAdminBuilder tlsTrustCertsFilePath(String tlsTrustCertsFilePath) {
        conf.setTlsTrustCertsFilePath(tlsTrustCertsFilePath);

View on GitHub (pinned to 820761864e)

Solutions

1. Verify the authPluginClass value matches an available Authentication implementation on the classpath.
2. Validate authParams against the plugin's expected format (e.g. OAuth2 JSON with issuerUrl, clientId, clientCredential).
3. Add the auth plugin dependency/jar to the application classpath.
4. Call .authentication(pluginClass, params) directly in a controlled place to get the underlying UnsupportedAuthenticationException with its real message.

Example fix

// before
props.put("authPluginClass", "com.example.MissingAuthPlugin");
builder.loadConf(props);
// after
props.put("authPluginClass", "org.apache.pulsar.client.impl.auth.AuthenticationToken");
props.put("authParams", "file:///etc/pulsar/token.txt");
builder.loadConf(props);

String plugin = props.getProperty("authPluginClass");
if (plugin != null) {
    try {
        Class<?> c = Class.forName(plugin);
        if (!Authentication.class.isAssignableFrom(c))
            throw new IllegalArgumentException(plugin + " is not an Authentication");
    } catch (ClassNotFoundException e) {
        throw new IllegalArgumentException("auth plugin not on classpath: " + plugin);
    }
}

try {
    builder.loadConf(props);
} catch (RuntimeException e) {
    if (e.getMessage().startsWith("Failed to create authentication")) {
        log.error("bad auth config: {}", e.getCause(), e);
    }
    throw e;
}

When it happens

Trigger: PulsarAdminBuilder.loadConf(props) where the properties include authPluginClass pointing to a class that doesn't exist, doesn't implement Authentication, or whose init() throws UnsupportedAuthenticationException for the supplied authParams.

Common situations: Typo in the fully-qualified plugin class name; auth plugin jar missing from the classpath; migrating from AuthenticationTls to OAuth2 (or vice versa) with stale properties files; passing JSON authParams the plugin can't parse.

Understand the failure class

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

Related errors

• Invalid broker configuration. Authentication must be enabled
• No athenz domain name specified
• Invalid allowed offset for athenz role token verification sp
• Allowed offset for athenz role token verification must not b
• UNSUPPORTED_ISSUER

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