quarkusio/quarkus · error · io.quarkus.runtime.configuration.ConfigurationException

TLS configuration name '' is set but the TLS registry is not

Error message

TLS configuration name '' is set but the TLS registry is not available.

What it means

When quarkus.datasource."x".reactive.tls-configuration-name is set, ReactivePoolUtil.configureSsl() resolves it via the injected TlsConfigurationRegistry. If the TLS registry is null — meaning the TLS registry support (quarkus-tls-registry) is not on the classpath/available — a ConfigurationException is thrown because the named TLS config can never be resolved.

Source

Thrown at extensions/reactive-datasource/runtime/src/main/java/io/quarkus/reactive/datasource/runtime/ReactivePoolUtil.java:172

        if (config.preparedStatementCacheSqlLimit().isPresent()) {
            connectOptions.setPreparedStatementCacheSqlLimit(config.preparedStatementCacheSqlLimit().getAsInt());
        }
    }

    /**
     * Apply SSL/TLS, reconnect, and hostname verification settings from the generic reactive
     * datasource config to connect options.
     * <p>
     * When a named TLS configuration is set via {@code tls-configuration-name}, it takes precedence
     * over manual SSL properties (trust-certificate-*, key-certificate-*, trust-all, hostname-verification-algorithm).
     */
    public static void configureSsl(SqlConnectOptions connectOptions,
            DataSourceReactiveRuntimeConfig config,
            TlsConfigurationRegistry tlsRegistry) {
        if (config.tlsConfigurationName().isPresent()) {
            String tlsConfigName = config.tlsConfigurationName().get();
            if (tlsRegistry == null) {
                throw new ConfigurationException(
                        "TLS configuration name '" + tlsConfigName + "' is set but the TLS registry is not available.");
            }
            Optional<TlsConfiguration> maybeTlsConfig = tlsRegistry.get(tlsConfigName);
            if (maybeTlsConfig.isEmpty()) {
                throw new ConfigurationException("Unable to find the TLS configuration '" + tlsConfigName
                        + "' for the reactive datasource.");
            }
            TlsConfiguration tlsConfig = maybeTlsConfig.get();
            ClientSSLOptions sslOptions = tlsConfig.getClientSSLOptions();
            if (sslOptions == null) {
                sslOptions = new ClientSSLOptions();
            }
            connectOptions.setSslOptions(sslOptions);

            if (hasManualSslProperties(config)) {
                log.warn("Manual SSL properties (trust-certificate-*, key-certificate-*, trust-all,"
                        + " hostname-verification-algorithm) are ignored when a named TLS configuration"
                        + " (tls-configuration-name=" + tlsConfigName + ") is set.");

View on GitHub (pinned to e1c734241f)

Solutions

Add the quarkus-tls-registry extension: add io.quarkus:quarkus-tls-registry to pom.xml
Remove quarkus.datasource."<name>".reactive.tls-configuration-name if you intend to use inline trust/keystore settings instead
Rebuild the application so the registry bean is generated

Example fix

<!-- before -->
<dependency>io.quarkus:quarkus-reactive-pg-client</dependency>
<!-- after -->
<dependency>io.quarkus:quarkus-tls-registry</dependency>
<dependency>io.quarkus:quarkus-reactive-pg-client</dependency>

Defensive patterns

Strategy: validation

Validate before calling

if (config.tlsConfigurationName().isPresent()
        && !CdiUtil.current().select(TlsConfigurationRegistry.class).isResolvable()) {
    throw new IllegalStateException("Add io.quarkus:quarkus-tls-registry to use tls-configuration-name");
}

Try / catch

try {
    ReactivePoolUtil.configureSsl(opts, config, registry);
} catch (ConfigurationException e) {
    throw new IllegalStateException("TLS registry missing: add quarkus-tls-registry extension", e);
}

Prevention

Add quarkus-tls-registry whenever tls-configuration-name is used
Check dependency list when porting datasource configs between projects
Prefer inline TLS properties if the registry extension is not desired

When it happens

Trigger: Setting quarkus.datasource."<name>".reactive.tls-configuration-name while the application lacks the quarkus-tls-registry extension (or a null registry is passed programmatically to configureSsl).

Common situations: Copying a datasource config that uses a named TLS configuration into a project that never added the TLS registry extension; using the reactive datasource without its TLS-registry-capable deployment.

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