quarkusio/quarkus · error · IllegalStateException

Unable to find the TLS configuration {{name}} for the mailer

Error message

Unable to find the TLS configuration {{name}} for the mailer {{mailerName}}.

What it means

A mailer can reference a named TLS configuration in the TlsConfigurationRegistry via quarkus.mailer.tls-configuration-name. If configureTLS cannot find a registered configuration with that name, it throws this IllegalStateException while building the Vert.x mail config.

Source

Thrown at extensions/mailer/runtime/src/main/java/io/quarkus/mailer/runtime/Mailers.java:296

        configureTLS(name, config, tlsRegistry, cfg);

        // Sets the metrics name so micrometer metrics will collect metrics for the client.
        // Because the mail client is _unnamed_, we only pass a prefix.
        // See io.quarkus.micrometer.runtime.binder.vertx.VertxMeterBinderAdapter.extractPrefix and
        // io.quarkus.micrometer.runtime.binder.vertx.VertxMeterBinderAdapter.extractClientName
        cfg.setMetricsName("mail");

        return cfg;
    }

    private void configureTLS(String name, MailerRuntimeConfig config, TlsConfigurationRegistry tlsRegistry, MailConfig cfg) {
        TlsConfiguration configuration = null;
        boolean defaultTrustAll = false;
        if (config.tlsConfigurationName().isPresent()) {
            Optional<TlsConfiguration> maybeConfiguration = tlsRegistry.get(config.tlsConfigurationName().get());
            if (!maybeConfiguration.isPresent()) {
                throw new IllegalStateException("Unable to find the TLS configuration "
                        + config.tlsConfigurationName().get() + " for the mailer " + name + ".");
            }
            configuration = maybeConfiguration.get();
        } else if (tlsRegistry.getDefault().isPresent() && tlsRegistry.getDefault().get().isTrustAll()) {
            defaultTrustAll = tlsRegistry.getDefault().get().isTrustAll();
            if (defaultTrustAll) {
                LOGGER.warn("The default TLS configuration is set to trust all certificates. This is a security risk."
                        + "Please use a named TLS configuration for the mailer " + name + " to avoid this warning.");
            }
        }

        if (configuration != null) {
            // SMTP is a bit convoluted here.
            // You can start a non-TLS connection and then upgrade to TLS (using the STARTTLS command).
            cfg.setSsl(config.tls().orElse(true));

            if (configuration.getTrustStoreOptions() != null) {
                cfg.setTrustOptions(configuration.getTrustStoreOptions());

View on GitHub (pinned to e1c734241f)

Solutions

Register the TLS configuration under the same name, e.g. quarkus.tls.my-tls.trust-store.jks.path=... then set quarkus.mailer.tls-configuration-name=my-tls.
Verify the exact name string matches between quarkus.tls.<name> and quarkus.mailer.tls-configuration-name.
If the default registry entry was intended, remove tls-configuration-name and rely on default TLS/trust-all settings instead.

Example fix

// before: mailer references a name nobody defines
quarkus.mailer.tls-configuration-name=smtp-tls

// after: define it in the TLS registry
quarkus.tls.smtp-tls.trust-store.jks.path=truststore.jks
quarkus.tls.smtp-tls.trust-store.jks.password=changeit
quarkus.mailer.tls-configuration-name=smtp-tls

Defensive patterns

Strategy: validation

Validate before calling

String tlsName = ConfigProvider.getConfig()
        .getOptionalValue("quarkus.mailer.tls-configuration-name", String.class).orElse(null);
if (tlsName != null
        && ConfigProvider.getConfig().getOptionalValue("quarkus.tls." + tlsName + ".trust-store.jks.path", String.class).isEmpty()) {
    throw new IllegalStateException("TLS configuration '" + tlsName + "' is not registered in quarkus.tls.*");
}

Try / catch

try {
    mailer.send(mail).await().indefinitely();
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Unable to find the TLS configuration")) {
        LOG.error("Define quarkus.tls.<name>.* or fix tls-configuration-name", e);
    }
    throw e;
}

Prevention

Reference TLS config names from constants shared with the quarkus.tls.* keys
Add a dev-mode startup check that resolves every named TLS configuration
When renaming a TLS block, grep for tls-configuration-name usages

When it happens

Trigger: quarkus.mailer.tls-configuration-name (or the named-mailer variant) set to a name not registered via quarkus.tls.<name>.* config or a TlsConfigurationRegistry custom provider.

Common situations: Typo in the TLS config name; the quarkus.tls.mailer-name config block was removed or renamed; referencing a named TLS config in an environment where the registry wasn't populated (missing quarkus-tls-registry usage or build-time registration).

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