apache/pulsar · error · IllegalStateException

Failed to initialize OAuth2 IdP TLS factory: ${cause.getMess

Error message

Failed to initialize OAuth2 IdP TLS factory: ${cause.getMessage}

What it means

The asynchronous OAuth2 IdP TLS-factory initialization completed exceptionally. The factory is closed and this IllegalStateException is thrown with the message suffixed by cause.getMessage() and the original cause attached. It indicates a TLS/keystore configuration problem surfaced during init.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/StandaloneOAuth2HttpClientFactory.java:117

        }
    }

    private static PulsarTlsFactory buildIdpTlsFactory(TlsPolicy policy, int refreshIntervalSeconds,
            ScheduledExecutorService executor) {
        FileBasedTlsFactory factory = new FileBasedTlsFactory(
                Map.of(TlsPurpose.CLIENT_OAUTH2, policy),
                FileBasedTlsFactorySettings.builder().refreshIntervalSeconds(refreshIntervalSeconds).build(),
                Map.of());
        try {
            factory.initialize(initContext(executor)).get();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            closeQuietly(factory);
            throw new IllegalStateException("Interrupted initializing OAuth2 IdP TLS factory", e);
        } catch (ExecutionException e) {
            closeQuietly(factory);
            Throwable cause = e.getCause() != null ? e.getCause() : e;
            throw new IllegalStateException("Failed to initialize OAuth2 IdP TLS factory: " + cause.getMessage(),
                    cause);
        }
        return factory;
    }

    private static TlsFactoryInitContext initContext(ScheduledExecutorService executor) {
        return new TlsFactoryInitContext() {
            @Override
            public Map<String, String> params() {
                return Map.of();
            }

            @Override
            public ScheduledExecutorService scheduler() {
                return executor;
            }

            @Override

View on GitHub (pinned to 820761864e)

Solutions

Read the wrapped cause (getCause()) — it names the actual TLS failure.
Verify the trust/key store file exists and is readable at the configured absolute path.
Check passwords and KeyStore type in the TLS config match the actual file format.
Confirm certificates are valid/unexpired and the JVM supports the configured TLS version/algorithm.

Example fix

// before
map.put("tlsTrustCertsFilePath", "/etc/certs/ca.pem"); // file missing -> init fails
// after
// ensure the file exists and is a valid PEM bundle first, then:
map.put("tlsTrustCertsFilePath", "/etc/certs/ca-bundle.crt");

Defensive patterns

Strategy: try-catch

Validate before calling

static void validateTlsFiles(Map<String,String> conf) {
    String path = conf.get("tlsTrustCertsFilePath");
    if (path != null && !java.nio.file.Files.isReadable(java.nio.file.Path.of(path))) {
        throw new IllegalStateException("Trust certs file not readable: " + path);
    }
}

Try / catch

try {
    client = AuthenticationFactoryOAuth2.clientCredentials(issuerUrl, credFile, audience);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Failed to initialize OAuth2 IdP TLS factory")) {
        // real reason is in the cause chain
        e.getCause().printStackTrace();
        throw new RuntimeException("Fix TLS config (keystore path/password/certs): " + e.getCause().getMessage(), e);
    }
    throw e;
}

Prevention

Always inspect getCause() — the message suffix only summarizes the root cause.
Use absolute paths for keystore/truststore files and verify readability at startup.
Match KeyStore type and password to the actual file format (JKS vs PKCS12 vs PEM).
Confirm certs are unexpired and the JVM supports the configured TLS version.

When it happens

Trigger: Any failure inside TLS factory initialization: SSLContext/keystore file missing or unreadable, wrong keystore/truststore password, unsupported TLS algorithm or provider, invalid PEM/key material in the oauth2 TLS config parameters.

Common situations: tlsTrustCertsFilePath pointing at a missing or non-PEM file; corrupt or expired certificates; wrong KeyStore type (JKS vs PKCS12); JDK lacking the requested TLS provider; relative paths resolved against the wrong working directory.

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/1ad669b9cc421b09. Report an issue: GitHub.