{"record":{"id":"ed8f0710d5ae626f","repo":"quarkusio/quarkus","slug":"no-suitable-template-variant-found","errorCode":null,"errorMessage":"No suitable template variant found","messagePattern":"No suitable template variant found","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/mailer/runtime/src/main/java/io/quarkus/mailer/runtime/MailTemplateInstanceImpl.java","lineNumber":147,"sourceCode":"        if (variantsAttr != null) {\n            List<Result> results = new ArrayList<>();\n            @SuppressWarnings(\"unchecked\")\n            List<Variant> variants = (List<Variant>) variantsAttr;\n            for (Variant variant : variants) {\n                if (variant.getContentType().equals(Variant.TEXT_HTML) || variant.getContentType().equals(Variant.TEXT_PLAIN)) {\n                    results.add(new Result(variant,\n                            Uni.createFrom().completionStage(\n                                    new Supplier<CompletionStage<? extends String>>() {\n                                        @Override\n                                        public CompletionStage<? extends String> get() {\n                                            return templateInstance\n                                                    .setAttribute(TemplateInstance.SELECTED_VARIANT, variant).renderAsync();\n                                        }\n                                    })));\n                }\n            }\n            if (results.isEmpty()) {\n                throw new IllegalStateException(\"No suitable template variant found\");\n            }\n            List<Uni<String>> unis = results.stream().map(Result::resolve).collect(Collectors.toList());\n            return Uni.combine().all().unis(unis)\n                    .combinedWith(combine(results))\n                    .chain(new Function<Mail, Uni<? extends Void>>() {\n                        @Override\n                        public Uni<? extends Void> apply(Mail m) {\n                            return mailer.send(m);\n                        }\n                    });\n        } else {\n            throw new IllegalStateException(\"No template variant found\");\n        }\n    }\n\n    private Function<List<?>, Mail> combine(List<Result> results) {\n        return new Function<List<?>, Mail>() {\n            @Override","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/mailer/runtime/src/main/java/io/quarkus/mailer/runtime/MailTemplateInstanceImpl.java#L129-L165","documentation":"When a mail template is sent, MailTemplateInstanceImpl collects the template variants (e.g. for text/html, text/plain content types) that match the requested content types and locales. If no variant matches — the results list is empty — send() throws IllegalStateException('No suitable template variant found') and no mail is sent.","triggerScenarios":"Calling mailTemplate.of(\"name\").to(...).send() where the template exists but none of its variants match the requested content type (e.g. template has only text/plain but mail is sent as HTML) or locale; often when the template name resolves to an empty/blank template with no variants.","commonSituations":"Typo or wrong directory for template files so only a partial variant loads; using quarkus.mailer.* without defining both HTML and text variants; sending with a locale for which no localized variant exists; template named via config property that is unset.","solutions":["Verify template files exist under src/main/resources/templates with correct names and extensions (.html/.txt for Qute)","Provide both HTML and plain-text variants (or a single variant matching the mail's content types) for the template name used","Check the locale/content-type selection logic — add a localized variant or send without forcing a locale","Verify the template name/path string passed to the MailTemplate is correct"],"exampleFix":"// before: only templates/mail/welcome.txt exists but mail sent as HTML\nmailTemplate.of(\"mail/welcome\").to(to).send(); // IllegalStateException\n// after: add src/main/resources/templates/mail/welcome.html (and keep welcome.txt)\nmailTemplate.of(\"mail/welcome\").to(to).send();","handlingStrategy":"validation","validationCode":"// ensure variants exist for both content types before sending\nTemplateInstance instance = mailTemplate.getInjectableTemplateInstance();\nif (mailTemplate.data() == null || !templateResourceExists(\"templates/mail/welcome.html\")) {\n    throw new IllegalStateException(\"mail template variant missing: add .html and .txt files under templates/\");\n}\nmailTemplate.of(\"mail/welcome\").to(to).send();","typeGuard":"boolean hasHtmlVariant(String templateName) {\n    return getClass().getResource(\"/templates/\" + templateName + \".html\") != null;\n}","tryCatchPattern":"try {\n    mailTemplate.of(\"mail/welcome\").to(to).send().await().indefinitely();\n} catch (IllegalStateException e) {\n    if (e.getMessage().contains(\"No suitable template variant\")) {\n        log.errorf(\"Template 'mail/welcome' lacks a variant for the requested content type/locale\");\n    }\n    throw e;\n}","preventionTips":["Ship both .html and .txt variants of every mail template","Keep template paths under src/main/resources/templates matching the name passed to of()","Test mail sending (Dev Services mailpit / MailHog) in CI before production","Avoid forcing locales unless localized variants exist for all of them"],"tags":["quarkus","mailer","templates","qute"],"backgroundTag":"no-matching-template-variant","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}