{"record":{"id":"5da32c1ea8779810","repo":"quarkusio/quarkus","slug":"unable-to-find-the-tls-configuration-name-for","errorCode":null,"errorMessage":"Unable to find the TLS configuration {{name}} for the mailer {{mailerName}}.","messagePattern":"Unable to find the TLS configuration (.+?)\\} for the mailer (.+?)\\}\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/mailer/runtime/src/main/java/io/quarkus/mailer/runtime/Mailers.java","lineNumber":296,"sourceCode":"\n        configureTLS(name, config, tlsRegistry, cfg);\n\n        // Sets the metrics name so micrometer metrics will collect metrics for the client.\n        // Because the mail client is _unnamed_, we only pass a prefix.\n        // See io.quarkus.micrometer.runtime.binder.vertx.VertxMeterBinderAdapter.extractPrefix and\n        // io.quarkus.micrometer.runtime.binder.vertx.VertxMeterBinderAdapter.extractClientName\n        cfg.setMetricsName(\"mail\");\n\n        return cfg;\n    }\n\n    private void configureTLS(String name, MailerRuntimeConfig config, TlsConfigurationRegistry tlsRegistry, MailConfig cfg) {\n        TlsConfiguration configuration = null;\n        boolean defaultTrustAll = false;\n        if (config.tlsConfigurationName().isPresent()) {\n            Optional<TlsConfiguration> maybeConfiguration = tlsRegistry.get(config.tlsConfigurationName().get());\n            if (!maybeConfiguration.isPresent()) {\n                throw new IllegalStateException(\"Unable to find the TLS configuration \"\n                        + config.tlsConfigurationName().get() + \" for the mailer \" + name + \".\");\n            }\n            configuration = maybeConfiguration.get();\n        } else if (tlsRegistry.getDefault().isPresent() && tlsRegistry.getDefault().get().isTrustAll()) {\n            defaultTrustAll = tlsRegistry.getDefault().get().isTrustAll();\n            if (defaultTrustAll) {\n                LOGGER.warn(\"The default TLS configuration is set to trust all certificates. This is a security risk.\"\n                        + \"Please use a named TLS configuration for the mailer \" + name + \" to avoid this warning.\");\n            }\n        }\n\n        if (configuration != null) {\n            // SMTP is a bit convoluted here.\n            // You can start a non-TLS connection and then upgrade to TLS (using the STARTTLS command).\n            cfg.setSsl(config.tls().orElse(true));\n\n            if (configuration.getTrustStoreOptions() != null) {\n                cfg.setTrustOptions(configuration.getTrustStoreOptions());","sourceCodeStart":278,"sourceCodeEnd":314,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/mailer/runtime/src/main/java/io/quarkus/mailer/runtime/Mailers.java#L278-L314","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","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."],"exampleFix":"// before: mailer references a name nobody defines\nquarkus.mailer.tls-configuration-name=smtp-tls\n\n// after: define it in the TLS registry\nquarkus.tls.smtp-tls.trust-store.jks.path=truststore.jks\nquarkus.tls.smtp-tls.trust-store.jks.password=changeit\nquarkus.mailer.tls-configuration-name=smtp-tls","handlingStrategy":"validation","validationCode":"String tlsName = ConfigProvider.getConfig()\n        .getOptionalValue(\"quarkus.mailer.tls-configuration-name\", String.class).orElse(null);\nif (tlsName != null\n        && ConfigProvider.getConfig().getOptionalValue(\"quarkus.tls.\" + tlsName + \".trust-store.jks.path\", String.class).isEmpty()) {\n    throw new IllegalStateException(\"TLS configuration '\" + tlsName + \"' is not registered in quarkus.tls.*\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    mailer.send(mail).await().indefinitely();\n} catch (IllegalStateException e) {\n    if (e.getMessage().startsWith(\"Unable to find the TLS configuration\")) {\n        LOG.error(\"Define quarkus.tls.<name>.* or fix tls-configuration-name\", e);\n    }\n    throw e;\n}","preventionTips":["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"],"tags":["quarkus","mailer","tls","configuration","startup"],"backgroundTag":"tls-configuration-not-found","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}