What causes "Failed to resolve the admin client TLS factory" in apache/pulsar?

Check the wrapped cause (e.getCause()) for the concrete TLS resolution failure.

apache/pulsar · error · RuntimeException

Failed to resolve the admin client TLS factory

Error message

Failed to resolve the admin client TLS factory

What it means

RuntimeException thrown when the shared PulsarTlsFactory for an admin client cannot be resolved via ClientTlsFactorySupport.resolveClientTlsFactory. The connector provider lazily creates one shared TLS factory plus an executor; any exception during resolution (bad TLS key/cert paths, keystore problems) shuts the executor down and aborts admin client creation.

Source

Thrown at pulsar-client-admin/src/main/java/org/apache/pulsar/client/admin/internal/http/AsyncHttpConnectorProvider.java:117

    synchronized TlsFactoryOwnership sharedTlsFactory() {
        if (sharedTlsFactory != null) {
            // Already resolved. The connectors borrow it: this provider stays the owner.
            return TlsFactoryOwnership.borrowing(sharedTlsFactory.factory());
        }
        if (!AsyncHttpConnector.needsTlsFactory(conf)) {
            sharedTlsFactory = TlsFactoryOwnership.none();
            return sharedTlsFactory;
        }
        ScheduledExecutorService executor = Executors.newSingleThreadScheduledExecutor(
                new DefaultThreadFactory("pulsar-admin-tls-factory"));
        try {
            sharedTlsFactory = TlsFactoryOwnership.owning(
                    ClientTlsFactorySupport.resolveClientTlsFactory(conf, executor, executor,
                            conf.getOpenTelemetry()),
                    executor);
        } catch (Exception e) {
            executor.shutdownNow();
            throw new RuntimeException("Failed to resolve the admin client TLS factory", e);
        }
        return TlsFactoryOwnership.borrowing(sharedTlsFactory.factory());
    }

    /**
     * Release the shared TLS factory and the executor driving its rotation. Called when the owning
     * {@code PulsarAdmin} closes; the connectors borrowed the factory and dispose only their own
     * subscriptions.
     */
    public synchronized void close() {
        if (sharedTlsFactory == null) {
            return;
        }
        sharedTlsFactory.close();
        sharedTlsFactory = TlsFactoryOwnership.none();
    }

    @VisibleForTesting

View on GitHub (pinned to 820761864e)

Solutions

Check the wrapped cause (e.getCause()) for the concrete TLS resolution failure.
Verify tlsCertificateFilePath and tlsKeyFilePath point to valid, readable PEM/keystore files.
Ensure the TLS trust store (tlsTrustCertsFilePath or default CA) is valid.
If TLS auth is enabled, confirm both client key and certificate files are configured.

Example fix

// before
PulsarAdmin admin = PulsarAdmin.builder().serviceHttpUrl("https://broker:8443")
    .tlsKeyFilePath("/missing/key.pem")
    .tlsCertificateFilePath("/missing/cert.pem")
    .build(); // RuntimeException: Failed to resolve the admin client TLS factory
// after
PulsarAdmin admin = PulsarAdmin.builder().serviceHttpUrl("https://broker:8443")
    .tlsKeyFilePath("/etc/pulsar/admin.key.pem")
    .tlsCertificateFilePath("/etc/pulsar/admin.cert.pem")
    .tlsTrustCertsFilePath("/etc/pulsar/ca.cert.pem")
    .build();

Defensive patterns

Strategy: validation

Validate before calling

for (String f : new String[]{tlsKeyFile, tlsCertFile, tlsTrustFile}) {
    if (f != null && !Files.isReadable(Paths.get(f)))
        throw new IllegalStateException("TLS file not readable: " + f);
}

Try / catch

try {
    PulsarAdmin admin = builder.build();
} catch (RuntimeException e) {
    if (e.getMessage().contains("Failed to resolve the admin client TLS factory")) {
        log.error("TLS setup failed: {}", e.getCause(), e);
    }
    throw e;
}

Prevention

Check all TLS file paths (key, cert, trust) exist and are readable at startup
Provide keystore passwords when files are encrypted
Only enable tlsAuthenticationEnabled when key+cert are configured
Validate PEM files with openssl before deploying

When it happens

Trigger: Building a PulsarAdmin over https (or with TLS auth configured) where TLS key/certificate files are missing, unreadable, malformed, or the configured PulsarTlsFactory initialization throws.

Common situations: Typo in tlsKeyFilePath/tlsCertificateFilePath; files not readable by the process user; password-protected keystore without provided password; enabling TLS auth (tlsAuthenticationEnabled) without supplying key/cert files.

Understand the failure class

SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

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