flowable/flowable-engine · error · FlowableIllegalArgumentException

When using email headers name and value must be defined colo

Error message

When using email headers name and value must be defined colon separated. (e.g. X-Attribute: value

What it means

Custom email headers passed to a mail activity must be 'name: value' pairs separated by colons, one per line. addHeader splits each line on ':' and throws FlowableIllegalArgumentException unless the line yields exactly two parts. This enforces a strict RFC-style header format.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/mail/BaseMailActivityDelegate.java:141

        message.setSubject(subjectStr);
        message.setPlainContent(textStr);
        message.setHtmlContent(htmlStr);
        if (charSetStr != null) {
            message.setCharset(Charset.forName(charSetStr));
        }
        addAttachments(message, variableContainer);

        return message;
    }

    protected void addHeader(MailMessage message, String headersStr) {
        if (headersStr == null) {
            return;
        }
        for (String headerEntry : headersStr.split(NEWLINE_REGEX)) {
            String[] split = headerEntry.split(":");
            if (split.length != 2) {
                throw new FlowableIllegalArgumentException("When using email headers name and value must be defined colon separated. (e.g. X-Attribute: value");
            }
            String name = split[0].trim();
            String value = split[1].trim();
            message.addHeader(name, value);
        }
    }

    protected void addAttachments(MailMessage message, V variableContainer) {
        if (attachments == null) {
            return;
        }

        Object value = attachments.getValue(variableContainer);
        if (value == null) {
            return;
        }
        if (value instanceof Collection<?> collection) {
            if (!collection.isEmpty()) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

Ensure each header line has exactly one colon separating name and value
If the value contains a colon, move it to the message body or encode it differently — the parser does not support values with ':'
Verify the headers field after expression/variable substitution contains no malformed or empty lines

Example fix

// before
String headers = "X-Attribute value\nX-Priority: 1";
// after
String headers = "X-Attribute: value\nX-Priority: 1";

Defensive patterns

Strategy: validation

Validate before calling

for (String line : headersStr.split("\\n")) {
    if (line.isBlank()) continue;
    int idx = line.indexOf(':');
    if (idx <= 0 || idx != line.lastIndexOf(':')) {
        throw new IllegalArgumentException("Bad header (need exactly one colon): " + line);
    }
}

Try / catch

try {
    // send mail with headers
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().startsWith("When using email headers")) {
        // sanitize/repair header string
    }
    throw e;
}

Prevention

Build headers programmatically (name/value pairs) and serialize to 'name: value' lines
Never allow ':' inside header values
Test header strings after variable substitution

When it happens

Trigger: The 'headers' field string contains a line without exactly one colon: no colon at all, or a value containing an extra colon (split on ':' yields 3+ parts), or an empty line fragment.

Common situations: Developers writing 'X-Attribute value' (missing colon) or 'X-Custom: a:b' (extra colon in value); copy-pasted multi-header blocks with wrong separators; template variables in headers expanding to malformed strings.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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