apache/pulsar · error · IllegalStateException

Failed to build TLS instanceClass for purpose purpose

Error message

Failed to build TLS instanceClass for purpose purpose

What it means

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.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/tls/impl/TlsFactoryProbe.java:58

    /**
     * Eagerly build (probe) the instance of {@code instanceClass} for {@code purpose}, returning the
     * retained handle. Blocks until the factory completes the request.
     *
     * @param factory       the factory to probe
     * @param purpose       the purpose to probe
     * @param instanceClass the well-known instance class to probe
     * @param <T>           the instance type
     * @return the retained handle whose {@link TlsHandle#get()} is the initial instance
     * @throws IllegalStateException if the factory does not support the {@code (purpose, class)}
     *                               combination, or completes the request exceptionally (a boot error)
     */
    public static <T> TlsHandle<T> probe(PulsarTlsFactory factory, TlsPurpose purpose, Class<T> instanceClass) {
        Optional<TlsHandle<T>> handle;
        try {
            handle = factory.createInstance(purpose, instanceClass).join();
        } catch (CompletionException e) {
            Throwable cause = e.getCause() != null ? e.getCause() : e;
            throw new IllegalStateException(
                    "Failed to build TLS " + instanceClass.getName() + " for purpose " + purpose, cause);
        }
        return handle.orElseThrow(() -> new IllegalStateException(
                "TLS factory does not support building " + instanceClass.getName() + " for purpose " + purpose));
    }
}

View on GitHub (pinned to 820761864e)

Solutions

1. Read the chained cause for the real TLS build failure (keystore errors, missing material)
2. Fix the TlsPolicy or material files indicated by the cause before re-probing
3. Confirm the purpose and instanceClass are actually supported before probing
4. Handle the probe's IllegalStateException in diagnostics code instead of surfacing an opaque CompletionException

Example fix

// before
TlsFactoryProbe.probe(factory, purpose, SslContext.class); // opaque failure
// after
try {
    TlsFactoryProbe.probe(factory, purpose, SslContext.class);
} catch (IllegalStateException e) {
    log.error("TLS probe failed: {}", e.getCause(), e.getCause()); // real cause
}

try {
    TlsFactoryProbe.probe(factory, purpose, SslContext.class);
} catch (IllegalStateException e) {
    Throwable root = e.getCause();
    log.error("TLS probe failed for {}: {}", purpose, root == null ? e.getMessage() : root.getMessage(), root);
}

When it happens

Trigger: Calling probe(factory, purpose, SslContext.class) when the underlying createInstance fails — e.g. unreadable keystore, wrong password, unavailable material — completing the future with CompletionException.

Common situations: 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.

Understand the failure class

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

Related errors

• (wraps subscribeAsync failure cause)
• Failed to obtain broker-client authentication TLS material
• The replication cluster does not provide TLS encrypted servi
• No ${scheme} URL configured for broker ${brokerId}
• Failed to initialize controller for ${topic}

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