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
- Set the 'html' field (or setHtmlContent) on the MailMessage / mail task configuration
- Or set the 'text' field (or setPlainContent) for a plain-text email
- In BPMN mail tasks, add <flowable:field name="html" ...> or name="text" to the task definition
- 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
- Always set html or text on MailMessage before send, even when attachments exist
- Validate mail task XML fields (text/html) in CI with a BPMN lint
- Check template rendering output is non-null before assigning to the mail body
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
- header name cannot be null or empty
- header value cannot be null or empty
- No recipient could be found for sending email for " +…
- A channel key detection value is required for the channel…
- A group or a user is required to create an identity link.
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)