quarkusio/quarkus · error · IllegalStateException

Unable to find the TLS configuration ${tlsConfigurationName}

Error message

Unable to find the TLS configuration ${tlsConfigurationName} for the gRPC client ${name}.

What it means

gRPC clients can reference a named TLS registry configuration via quarkus.grpc.clients.<name>.tls-configuration-name. Channels.createChannel looks the name up in the TlsConfigurationRegistry; if the registry contains no configuration with that name, channel creation aborts with IllegalStateException naming the missing TLS config and the client.

Source

Thrown at extensions/grpc/runtime/src/main/java/io/quarkus/grpc/runtime/supports/Channels.java:174

        GrpcClientOptions clientOptions = new GrpcClientOptions()
                .setMaxMessageSize(clientConfig.maxInboundMessageSize().orElse(DEFAULT_MAX_MESSAGE_SIZE));

        for (ChannelBuilderCustomizer customizer : channelBuilderCustomizers) {
            customizer.customize(name, clientConfig, clientOptions);
        }

        if (!plainText) {
            TlsConfigurationRegistry registry = Arc.container().select(TlsConfigurationRegistry.class).get();

            // always set ssl + alpn for plain-text=false
            options.setSsl(true);
            options.setUseAlpn(true);

            TlsConfiguration configuration = null;
            if (clientConfig.tlsConfigurationName().isPresent()) {
                Optional<TlsConfiguration> maybeConfiguration = registry.get(clientConfig.tlsConfigurationName().get());
                if (!maybeConfiguration.isPresent()) {
                    throw new IllegalStateException("Unable to find the TLS configuration "
                            + clientConfig.tlsConfigurationName().get() + " for the gRPC client " + name + ".");
                }
                configuration = maybeConfiguration.get();
            } else if (registry.getDefault().isPresent() && (registry.getDefault().get().getTrustStoreOptions() != null
                    || registry.getDefault().get().isTrustAll())) {
                configuration = registry.getDefault().get();
            }

            if (configuration != null) {
                TlsConfigUtils.configure(options, configuration);
            } else if (clientConfig.tls().enabled()) {
                GrpcClientConfiguration.TlsClientConfig tls = clientConfig.tls();
                options.setSsl(true).setTrustAll(tls.trustAll());

                configurePemTrustOptions(options, tls.trustCertificatePem());
                configureJksTrustOptions(options, tls.trustCertificateJks());
                configurePfxTrustOptions(options, tls.trustCertificateP12());

View on GitHub (pinned to e1c734241f)

Solutions

Define the named TLS configuration, e.g. quarkus.tls.myTls.key-store.p12.path=... / quarkus.tls.myTls.trust-store.... matching the referenced name exactly.
Fix typos in quarkus.grpc.clients.<name>.tls-configuration-name.
Ensure the TLS registry dependency (io.quarkus:quarkus-tls-registry) and any keystore provider dependencies are present.
Verify keystore/truststore files exist on the runtime classpath or at the configured filesystem path.

Example fix

// before
quarkus.grpc.clients.hello.tls-configuration-name=myTls
# no quarkus.tls.myTls.* defined

// after
quarkus.grpc.clients.hello.tls-configuration-name=myTls
quarkus.tls.myTls.key-store.p12.path=certs/client.p12
quarkus.tls.myTls.key-store.p12.password=secret
quarkus.tls.myTls.trust-store.pem.paths=certs/ca.pem

Defensive patterns

Strategy: validation

Validate before calling

// resolve the named TLS config before creating the channel
String tlsName = config.getValue("quarkus.grpc.clients.hello.tls-configuration-name", String.class);
boolean defined = ConfigProvider.getConfig().getPropertyNames().stream()
    .anyMatch(p -> p.startsWith("quarkus.tls." + tlsName + "."));
if (!defined) {
    throw new IllegalStateException("TLS config '" + tlsName + "' is not defined (quarkus.tls." + tlsName + ".*)");
}

Try / catch

try {
    channel = Channels.createChannel("hello", interceptors);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("Unable to find the TLS configuration")) {
        throw new ConfigurationException("Define quarkus.tls.<name>.* for the referenced tls-configuration-name", e);
    }
    throw e;
}

Prevention

Keep TLS config names in a constants class referenced by both the tls.* block and clients.
Add the quarkus-tls-registry extension and keystore files to the deployment checklist.
Verify TLS configs resolve in a startup health check across all profiles.

When it happens

Trigger: quarkus.grpc.clients.<name>.tls-configuration-name=myTls is set but no matching quarkus.tls.key-store/cert-store... myTls.* configuration block exists (or the TLS registry extension that defines it is missing) when the channel is created.

Common situations: Typo in the tls-configuration-name value; defining the TLS config only for another profile; forgetting to add the quarkus-tls-registry dependency or the keystore files not packaged; renaming the TLS config without updating client references.

Understand the failure class

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

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/b98d8f67ee94768e. Report an issue: GitHub.