{"record":{"id":"1ad669b9cc421b09","repo":"apache/pulsar","slug":"failed-to-initialize-oauth2-idp-tls-factory-cau","errorCode":null,"errorMessage":"Failed to initialize OAuth2 IdP TLS factory: ${cause.getMessage}","messagePattern":"Failed to initialize OAuth2 IdP TLS factory: (.+?)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/StandaloneOAuth2HttpClientFactory.java","lineNumber":117,"sourceCode":"        }\n    }\n\n    private static PulsarTlsFactory buildIdpTlsFactory(TlsPolicy policy, int refreshIntervalSeconds,\n            ScheduledExecutorService executor) {\n        FileBasedTlsFactory factory = new FileBasedTlsFactory(\n                Map.of(TlsPurpose.CLIENT_OAUTH2, policy),\n                FileBasedTlsFactorySettings.builder().refreshIntervalSeconds(refreshIntervalSeconds).build(),\n                Map.of());\n        try {\n            factory.initialize(initContext(executor)).get();\n        } catch (InterruptedException e) {\n            Thread.currentThread().interrupt();\n            closeQuietly(factory);\n            throw new IllegalStateException(\"Interrupted initializing OAuth2 IdP TLS factory\", e);\n        } catch (ExecutionException e) {\n            closeQuietly(factory);\n            Throwable cause = e.getCause() != null ? e.getCause() : e;\n            throw new IllegalStateException(\"Failed to initialize OAuth2 IdP TLS factory: \" + cause.getMessage(),\n                    cause);\n        }\n        return factory;\n    }\n\n    private static TlsFactoryInitContext initContext(ScheduledExecutorService executor) {\n        return new TlsFactoryInitContext() {\n            @Override\n            public Map<String, String> params() {\n                return Map.of();\n            }\n\n            @Override\n            public ScheduledExecutorService scheduler() {\n                return executor;\n            }\n\n            @Override","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-client/src/main/java/org/apache/pulsar/client/impl/auth/oauth2/StandaloneOAuth2HttpClientFactory.java#L99-L135","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nmap.put(\"tlsTrustCertsFilePath\", \"/etc/certs/ca.pem\"); // file missing -> init fails\n// after\n// ensure the file exists and is a valid PEM bundle first, then:\nmap.put(\"tlsTrustCertsFilePath\", \"/etc/certs/ca-bundle.crt\");","handlingStrategy":"try-catch","validationCode":"static void validateTlsFiles(Map<String,String> conf) {\n    String path = conf.get(\"tlsTrustCertsFilePath\");\n    if (path != null && !java.nio.file.Files.isReadable(java.nio.file.Path.of(path))) {\n        throw new IllegalStateException(\"Trust certs file not readable: \" + path);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    client = AuthenticationFactoryOAuth2.clientCredentials(issuerUrl, credFile, audience);\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Failed to initialize OAuth2 IdP TLS factory\")) {\n        // real reason is in the cause chain\n        e.getCause().printStackTrace();\n        throw new RuntimeException(\"Fix TLS config (keystore path/password/certs): \" + e.getCause().getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["oauth2","tls","ssl","initialization","pulsar-client"],"backgroundTag":"tls-initialization-failed","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"}