flowable/flowable-engine · error · FlowableIllegalArgumentException

'html' or 'text' is required to be defined when sending an…

Error message

'html' or 'text' is required to be defined when sending an email

What it means

setContent() requires an email body: when both html and plain text content of the MailMessage are null, it throws FlowableIllegalArgumentException. An email with attachments but no body is also rejected. This is a validation guard ensuring the MIME message always has content.

Solutions

  1. Set the 'html' field (or setHtmlContent) on the MailMessage / mail task configuration
  2. Or set the 'text' field (or setPlainContent) for a plain-text email
  3. In BPMN mail tasks, add <flowable:field name="html" ...> or name="text" to the task definition
  4. If the body is intentionally empty, send a minimal body like a space or placeholder

Example fix

// before (BPMN mail task)
<flowable:field name="to" expression="${to}" />
// after
<flowable:field name="to" expression="${to}" />
<flowable:field name="html">
  <flowable:expression>${content}</flowable:expression>
</flowable:field>
Defensive patterns

Strategy: validation

Validate before calling

if (mailMessage.getPlainContent() == null && mailMessage.getHtmlContent() == null) {
    throw new IllegalArgumentException("Email body required: set text or html before sending");
}

Try / catch

try {
    mailClient.send(mailMessage);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().contains("'html' or 'text' is required")) {
        log.error("Mail task is missing its body content");
    }
}

Prevention

When it happens

Trigger: Sending via the mail activity/send API with a MailMessage where setPlainContent(null)/no text and setHtmlContent(null)/no html were set — even when attachments are present.

Common situations: BPMN mail task XML omitting the html/text fields; building MailMessage programmatically and forgetting to set body; template rendering producing null/empty so content never gets assigned; setting only attachments.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors


AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/5ba360228c0b97b8. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java:258

    }

    protected void setSentDate(MimeMessage message) {
        try {
            if (message.getSentDate() == null) {
                message.setSentDate(new Date());
            }
        } catch (MessagingException e) {
            throw new FlowableMailException("Failed to set send date", e);
        }
    }

    protected void setContent(MimeMessage mimeMessage, MailMessage message, String charset) {
        String text = message.getPlainContent();
        String html = message.getHtmlContent();
        Collection<DataSource> attachments = message.getAttachments();
        boolean attachmentsExists = attachments != null && !attachments.isEmpty();
        if (html == null && text == null) {
            throw new FlowableIllegalArgumentException("'html' or 'text' is required to be defined when sending an email");
        }
        if (html == null && !attachmentsExists) {
            try {
                mimeMessage.setText(text, charset);
            } catch (MessagingException e) {
                throw new FlowableMailException("Could not create text-only email", e);
            }
        } else {
            try {
                mimeMessage.setContent(createMultiPartContent(text, html, charset, attachments));
            } catch (MessagingException e) {
                throw new FlowableMailException("Failed to create multi part email", e);
            }
        }
    }

    protected MimeMultipart createMultiPartContent(String text, String html, String charset, Collection<DataSource> attachments) throws MessagingException {
        boolean attachmentsExists = attachments != null && !attachments.isEmpty();

View on GitHub (pinned to d6d39ce1c6)