What causes "Unable to find the TLS configuration for name ${name}." in quarkusio/quarkus?

Define the named configuration in application.properties: quarkus.tls.my-name.key-store.* (or trust-store.*)

quarkusio/quarkus · error · IllegalStateException

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

Error message

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

What it means

TlsConfiguration.from looks up a named TLS configuration in the TlsConfigurationRegistry and throws when the requested name is not registered. Named TLS configurations (beyond the default) must be declared via quarkus.tls.<name>.* properties or registered programmatically before they can be resolved.

Source

Thrown at extensions/tls-registry/spi/src/main/java/io/quarkus/tls/TlsConfiguration.java:23

import javax.net.ssl.SSLContext;

import io.vertx.core.net.ClientSSLOptions;
import io.vertx.core.net.KeyCertOptions;
import io.vertx.core.net.SSLEngineOptions;
import io.vertx.core.net.ServerSSLOptions;
import io.vertx.core.net.TrustOptions;

/**
 * The transport layer security configuration.
 */
public interface TlsConfiguration {

    static Optional<TlsConfiguration> from(TlsConfigurationRegistry registry, Optional<String> name) {
        if (name.isPresent()) {
            Optional<TlsConfiguration> maybeConfiguration = registry.get(name.get());
            if (maybeConfiguration.isEmpty()) {
                throw new IllegalStateException("Unable to find the TLS configuration for name " + name.get() + ".");
            }
            return maybeConfiguration;
        }
        return Optional.empty();
    }

    /**
     * Returns the key store.
     *
     * @return the key store if configured.
     */
    KeyStore getKeyStore();

    /**
     * Returns the key store options.
     *
     * @return the key store options if configured.
     */

View on GitHub (pinned to e1c734241f)

Solutions

Define the named configuration in application.properties: quarkus.tls.my-name.key-store.* (or trust-store.*)
Fix the tls-configuration-name / tls-config-name reference to match the registered name exactly
Verify the config source actually loads (right profile, right config file) — log registry contents or check startup config
In tests, add the @InjectMock-less real config or set the quarkus.tls.<name>.* properties

Example fix

// before (reference without definition)
quarkus.rest-client.my-client.tls-configuration-name=externl-tls
// after (matching definition)
quarkus.rest-client.my-client.tls-configuration-name=external-tls
quarkus.tls.external-tls.trust-store.p12.path=/etc/certs/trust.p12
quarkus.tls.external-tls.trust-store.p12.password=changeit

Defensive patterns

Strategy: validation

Validate before calling

// verify the named TLS config exists before using it
String name = "external-tls";
boolean defined = ConfigProvider.getConfig().getPropertyNames().stream()
        .anyMatch(p -> p.startsWith("quarkus.tls." + name + "."));
if (!defined) throw new IllegalStateException("TLS config not defined: " + name);

Try / catch

try {
    TlsConfiguration cfg = TlsConfiguration.from(registry, Optional.of(name));
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Unable to find the TLS configuration")) {
        log.errorf("TLS config '%s' not registered; define quarkus.tls.%s.* properties", name, name);
    }
}

Prevention

Centralize the TLS configuration name as a constant shared by producer and consumers
Use registry.get(name) or TlsConfigurationRegistry lookups returning Optional when absence is acceptable
Add a startup check that all referenced tls-configuration-name values resolve
Keep property definitions and references in the same config file/review

When it happens

Trigger: Calling TlsConfiguration.from(registry, Optional.of("my-name")) (directly or via REST client / gRPC / mail config referencing tls-configuration-name=my-name) when no quarkus.tls.my-name.* configuration exists in the registry.

Common situations: Typo in tls-configuration-name reference; TLS config defined under a different property prefix; named config not registered in tests (no quarkus.tls.* properties); using a named config from an extension that initialized before the registry was populated.

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/97101b821c2920c4. Report an issue: GitHub.