What causes "The `mails` parameter must not be `null`" in quarkusio/quarkus?

Never pass a null array — pass an empty array or skip the call when there is nothing to send.

quarkusio/quarkus · warning · IllegalArgumentException

The `mails` parameter must not be `null`

Error message

The `mails` parameter must not be `null`

What it means

MutinyMailerImpl.send(Mail... mails) accepts a varargs array of Mail objects. A null array reference cannot be iterated, so the method immediately rejects it with this IllegalArgumentException before doing any work.

Source

Thrown at extensions/mailer/runtime/src/main/java/io/quarkus/mailer/runtime/MutinyMailerImpl.java:78

    MutinyMailerImpl(Vertx vertx, MailClient client, MockMailboxImpl mockMailbox,
            String from, String bounceAddress, boolean mock, List<Pattern> approvedRecipients,
            boolean logRejectedRecipients, boolean logInvalidRecipients, Event<SentMail> sentEmailEvent) {
        this.vertx = vertx;
        this.client = client;
        this.mockMailbox = mockMailbox;
        this.from = from;
        this.bounceAddress = bounceAddress;
        this.mock = mock;
        this.approvedRecipients = approvedRecipients;
        this.logRejectedRecipients = logRejectedRecipients;
        this.logInvalidRecipients = logInvalidRecipients;
        this.sentEmailEvent = sentEmailEvent;
    }

    @Override
    public Uni<Void> send(Mail... mails) {
        if (mails == null) {
            throw new IllegalArgumentException("The `mails` parameter must not be `null`");
        }

        List<Uni<Void>> unis = stream(mails)
                .map(new Function<Mail, Uni<Void>>() {
                    @Override
                    public Uni<Void> apply(Mail mail) {
                        return MutinyMailerImpl.this.toMailMessage(mail)
                                .chain(new Function<MailMessage, Uni<? extends Void>>() {
                                    @Override
                                    public Uni<? extends Void> apply(MailMessage mailMessage) {
                                        return send(mail, mailMessage);
                                    }
                                });
                    }
                })
                .collect(Collectors.toList());

        return Uni.combine().all().unis(unis).discardItems();

View on GitHub (pinned to e1c734241f)

Solutions

Never pass a null array — pass an empty array or skip the call when there is nothing to send.
Null-check the array at the call site before invoking send().
If sending one message, construct it explicitly: reactiveMailer.send(Mail.withText(to, subject, body)).

Example fix

// before
reactiveMailer.send(mails); // mails may be null

// after
if (mails != null && mails.length > 0) {
    reactiveMailer.send(mails);
}

Defensive patterns

Strategy: type-guard

Validate before calling

if (mails == null || mails.length == 0) {
    LOG.info("Nothing to send");
    return Uni.createFrom().voidItem();
}

Type guard

static boolean isSendable(Mail[] mails) {
    return mails != null && mails.length > 0 && Arrays.stream(mails).allMatch(Objects::nonNull);
}

Try / catch

try {
    reactiveMailer.send(mails).await().indefinitely();
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("must not be `null`")) {
        LOG.error("send() was called with a null Mail array", e);
    }
    throw e;
}

Prevention

Wrap send() in your own helper that rejects null/empty input
Never pass varargs from nullable collections without a null check
Prefer sending a single Mail object over building arrays when possible

When it happens

Trigger: Calling reactiveMailer.send((Mail[]) null) or passing a null Mail[] variable into send(); generic code that forwards a nullable array parameter directly to the mailer.

Common situations: Building a Mail[] from a nullable collection with toArray on a null list; reflection or framework code supplying null varargs; confusing send(Mail...) with send(Mail) and passing null intending a single null mail.

Related errors

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