apache/pulsar · error · IllegalStateException

Interrupted while probing the client TLS factory

Error message

Interrupted while probing the client TLS factory

What it means

During probe(), waiting for the asynchronous TlsContextAcquisition.acquireNettyContext future was interrupted. The method restores the interrupt flag and rethrows as IllegalStateException. This means the calling thread was interrupted while the TLS factory was being validated.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/tls/ClientTlsFactorySupport.java:626

     * {@link TlsContextAcquisition}, so a custom factory that supplies only the JDK {@code SSLContext}
     * fallback probes successfully via the framework-synthesized Netty context.
     *
     * @param factory   the initialized factory
     * @param purpose   the purpose to probe
     * @param synthesis the settings baked into a synthesized Netty context on the fallback path
     */
    public static void probe(PulsarTlsFactory factory, TlsPurpose purpose, TlsSynthesisSpec synthesis) {
        try {
            Optional<TlsHandle<SslContext>> handle =
                    TlsContextAcquisition.acquireNettyContext(factory, purpose, synthesis).get();
            if (handle.isEmpty()) {
                throw new IllegalStateException("Client TLS factory " + factory.getClass().getName()
                        + " supplied no Netty SslContext for purpose " + purpose);
            }
            handle.get().dispose();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IllegalStateException("Interrupted while probing the client TLS factory", e);
        } catch (ExecutionException | CompletionException e) {
            Throwable cause = e.getCause() != null ? e.getCause() : e;
            throw new IllegalArgumentException("Client TLS configuration is invalid for purpose " + purpose
                    + ": " + cause.getMessage(), cause);
        }
    }

    private static void initializeBlocking(PulsarTlsFactory factory, TlsFactoryInitContext context)
            throws Exception {
        try {
            factory.initialize(context).get();
        } catch (ExecutionException e) {
            Throwable cause = e.getCause() != null ? e.getCause() : e;
            if (cause instanceof Exception ex) {
                throw ex;
            }
            throw new RuntimeException(cause);
        }

View on GitHub (pinned to 820761864e)

Solutions

1. Find what interrupted the thread (shutdown hook, executor shutdownNow, timeout) and delay client creation until after those run.
2. Retry PulsarClient creation on a non-interrupted thread.
3. Avoid interrupting threads that are building clients; use separate lifecycle coordination.
4. If intentional shutdown, catch the IllegalStateException and treat client setup as aborted.

Example fix

// before
executor.shutdownNow();
PulsarClient client = PulsarClient.builder().build(); // may be interrupted
// after
PulsarClient client = PulsarClient.builder().build();
executor.shutdownNow();

if (Thread.currentThread().isInterrupted()) {
    // clear/decide before doing TLS setup
    Thread.interrupted();
}

try {
    ClientTlsFactorySupport.probe(factory, purpose, spec);
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Interrupted while probing")) {
        Thread.currentThread().interrupt(); // preserve status, abort setup
    }
}

When it happens

Trigger: Thread calling resolveClientTlsFactory (e.g. during PulsarClient creation) is interrupted via Thread.interrupt() while blocked on the acquisition future.

Common situations: Application shutdown/executors interrupting client-construction threads; timeout watchdogs cancelling slow TLS init; mismanaged thread pools interrupting tasks.

Understand the failure class

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

Related errors

• Interrupted while connecting metadata store
• The replication cluster does not provide TLS encrypted servi
• No ${scheme} URL configured for broker ${brokerId}
• Issuer URL does not use https, but must:
• Failed to get TLS certificates from client

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