flowable/flowable-engine · error · FlowableIllegalArgumentException

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

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.

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)

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>

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

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");
    }
}

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

• No recipient could be found for sending email for " + variab
• header name cannot be null or empty
• header value cannot be null or empty
• Error retrieving app engine info
• Could not find an app definition with id '<appDefinitionId>

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