{"record":{"id":"7131be976c259021","repo":"apache/pulsar","slug":"failed-to-build-tls-instanceclass-for-purpose-purp","errorCode":null,"errorMessage":"Failed to build TLS instanceClass for purpose purpose","messagePattern":"Failed to build TLS instanceClass for purpose purpose","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"pulsar-common/src/main/java/org/apache/pulsar/common/tls/impl/TlsFactoryProbe.java","lineNumber":58,"sourceCode":"    /**\n     * Eagerly build (probe) the instance of {@code instanceClass} for {@code purpose}, returning the\n     * retained handle. Blocks until the factory completes the request.\n     *\n     * @param factory       the factory to probe\n     * @param purpose       the purpose to probe\n     * @param instanceClass the well-known instance class to probe\n     * @param <T>           the instance type\n     * @return the retained handle whose {@link TlsHandle#get()} is the initial instance\n     * @throws IllegalStateException if the factory does not support the {@code (purpose, class)}\n     *                               combination, or completes the request exceptionally (a boot error)\n     */\n    public static <T> TlsHandle<T> probe(PulsarTlsFactory factory, TlsPurpose purpose, Class<T> instanceClass) {\n        Optional<TlsHandle<T>> handle;\n        try {\n            handle = factory.createInstance(purpose, instanceClass).join();\n        } catch (CompletionException e) {\n            Throwable cause = e.getCause() != null ? e.getCause() : e;\n            throw new IllegalStateException(\n                    \"Failed to build TLS \" + instanceClass.getName() + \" for purpose \" + purpose, cause);\n        }\n        return handle.orElseThrow(() -> new IllegalStateException(\n                \"TLS factory does not support building \" + instanceClass.getName() + \" for purpose \" + purpose));\n    }\n}\n","sourceCodeStart":40,"sourceCodeEnd":65,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-common/src/main/java/org/apache/pulsar/common/tls/impl/TlsFactoryProbe.java#L40-L65","documentation":"TlsFactoryProbe.probe is a diagnostic that synchronously builds a TLS instance of the requested class for a purpose. If the asynchronous createInstance future completes exceptionally, the CompletionException is unwrapped and rethrown as IllegalStateException naming the instance class and purpose, keeping the original cause chained.","triggerScenarios":"Calling probe(factory, purpose, SslContext.class) when the underlying createInstance fails — e.g. unreadable keystore, wrong password, unavailable material — completing the future with CompletionException.","commonSituations":"Startup health-check against a misconfigured TLS policy; probing a purpose whose material was rotated out or deleted; using probe to validate configuration before serving traffic.","solutions":["Read the chained cause for the real TLS build failure (keystore errors, missing material)","Fix the TlsPolicy or material files indicated by the cause before re-probing","Confirm the purpose and instanceClass are actually supported before probing","Handle the probe's IllegalStateException in diagnostics code instead of surfacing an opaque CompletionException"],"exampleFix":"// before\nTlsFactoryProbe.probe(factory, purpose, SslContext.class); // opaque failure\n// after\ntry {\n    TlsFactoryProbe.probe(factory, purpose, SslContext.class);\n} catch (IllegalStateException e) {\n    log.error(\"TLS probe failed: {}\", e.getCause(), e.getCause()); // real cause\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    TlsFactoryProbe.probe(factory, purpose, SslContext.class);\n} catch (IllegalStateException e) {\n    Throwable root = e.getCause();\n    log.error(\"TLS probe failed for {}: {}\", purpose, root == null ? e.getMessage() : root.getMessage(), root);\n}","preventionTips":["Use probe in startup health checks and surface the chained cause, not the wrapper","Fix underlying material/policy errors before re-probing","Confirm purpose/instanceClass support before probing"],"tags":["tls","diagnostics","async","wrapped-exception"],"backgroundTag":"tls-instance-build-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"}