What causes "Unknown mailer " + name" in quarkusio/quarkus?

quarkusio/quarkus · error · IllegalArgumentException

Unknown mailer " + name

Error message

Unknown mailer " + name

What it means

MailResource.select() maps a mailer name taken from a request path/query parameter to one of four injected Mailer instances (TLS-registry variants with and without trust-all). If the name matches none of the known cases, the switch's default branch throws IllegalArgumentException('Unknown mailer ' + name). This is an application-level routing guard protecting against requests naming a mailer the test resource does not expose.

Source

Thrown at integration-tests/mailer/src/main/java/io/quarkus/it/mailer/MailResource.java:52

    @MailerName("tls-registry")
    Mailer tlsRegistryMailer;

    @MailerName("tls-registry-trust-all")
    Mailer tlsRegistryMailerWithTrustAll;

    @MailerName("custom-credentials-provider")
    Mailer mailerWithCustomCredentialsProvider;

    private Mailer select(String name) {
        if (name == null) {
            return defaultMailer;
        }
        return switch (name) {
            case "start-tls-registry" -> startTlsRegistryMailer;
            case "start-tls-registry-trust-all" -> startTlsRegistryMailerWithTrustAll;
            case "tls-registry" -> tlsRegistryMailer;
            case "tls-registry-trust-all" -> tlsRegistryMailerWithTrustAll;
            default -> throw new IllegalArgumentException("Unknown mailer " + name);
        };
    }

    @Inject
    Vertx vertx;

    @CheckedTemplate
    static class Templates {
        public static native MailTemplate.MailTemplateInstance hello(String name);
    }

    /**
     * Send a simple text email.
     */
    @GET
    @Path("/text")
    public String sendSimpleTextEmail() {
        return sendSimpleTextEmailWithCustomMailer(null);

View on GitHub (pinned to e1c734241f)

Solutions

Use one of the supported names: start-tls-registry, start-tls-registry-trust-all, tls-registry, tls-registry-trust-all
Check the name for typos and exact kebab-case spelling/case
Inspect MailResource.java to see the currently registered mailer instances injected via @Inject
If a new mailer variant is needed, add an injected Mailer field and a new case in the switch

Example fix

// before
curl http://localhost:8080/mailer/send/tls-trust-all
// after
curl http://localhost:8080/mailer/send/tls-registry-trust-all

Defensive patterns

Strategy: validation

Validate before calling

private static final Set<String> VALID_MAILERS = Set.of(
    "start-tls-registry", "start-tls-registry-trust-all",
    "tls-registry", "tls-registry-trust-all");

if (!VALID_MAILERS.contains(name)) {
    throw new WebApplicationException(
        Response.status(400).entity("Unknown mailer: " + name).build());
}

Try / catch

try {
    mailer = select(name);
} catch (IllegalArgumentException e) {
    return Response.status(Response.Status.BAD_REQUEST)
        .entity("Unknown mailer: " + name).build();
}

Prevention

Keep the set of valid mailer names as a shared constant used by both tests and the resource
Return HTTP 400 with a list of valid names instead of leaking IllegalArgumentException as a 500
Add a test asserting the rejection message lists valid options
Validate the path parameter with a JAX-RS @Pattern annotation before it reaches select()

When it happens

Trigger: Calling any endpoint of MailResource (e.g. /mailer/send/{name}) with a name other than 'start-tls-registry', 'start-tls-registry-trust-all', 'tls-registry', or 'tls-registry-trust-all' — e.g. a typo like 'tls-registry-trustall', an old name like 'default', or an empty/missing parameter.

Common situations: Hand-crafted curl/browser requests to the integration-test endpoint; renaming mailers in the resource but not updating test clients or documentation; case-sensitivity mistakes ('TLS-Registry'); copy-pasting an endpoint path from a different test application.

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/e3c50a1be1e3b892. Report an issue: GitHub.