flowable/flowable-engine · error · FlowableMailException

Could not encode attachment file name

Error message

Could not encode attachment file name

What it means

Attachment file names are MIME-encoded with MimeUtility.encodeText(name, charset, null) so non-ASCII names survive transport. If the charset is unsupported or the encoding fails, an UnsupportedEncodingException is wrapped as FlowableMailException "Could not encode attachment file name".

Solutions

1. Check the nested UnsupportedEncodingException for the offending charset name
2. Set the mail task charSet to a standard supported value like UTF-8
3. Verify with Charset.isSupported(charset) before sending
4. Ensure the JVM's full charset set is available (not a reduced/compact runtime)

Example fix

// before
<flowable:field name="charSet"><flowable:string>ISO-8859</flowable:string></flowable:field>
// after
<flowable:field name="charSet"><flowable:string>UTF-8</flowable:string></flowable:field>

if (charset != null && !java.nio.charset.Charset.isSupported(charset)) {
    throw new IllegalArgumentException("Cannot MIME-encode attachments with charset: " + charset);
}

try {
    mailClient.send(mailMessage);
} catch (FlowableMailException e) {
    if (e.getMessage().contains("Could not encode attachment file name")) {
        log.error("Attachment filename encoding failed; fix configured charset", e.getCause());
    }
}

When it happens

Trigger: Sending an email with attachments where the configured charset is not recognized by the JVM's Jakarta Mail MimeUtility, causing UnsupportedEncodingException during bodyPart.setFileName(...).

Common situations: Typo'd charset in mail task configuration (e.g. 'utf8' alias differences, 'ISO-8859' missing the -1); charset removed from the JVM (compact profiles/missing charsets); attachment names in exotic encodings with an incompatible charset.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Could not create text-only email
• The dmn xml is not properly encoded
• Cannot find task with id
• Cannot find task with id
• Could not add as recipient

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

Appendix: source

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

                    msgHtml.setContent(html, CONTENT_TYPE_TEXT_HTML);
                }
            }
        }

        if (StringUtils.isNotEmpty(text)) {
            MimeBodyPart msgText = new MimeBodyPart();
            bodyContainer.addBodyPart(msgText, 0);
            msgText.setText(text, charset);
        }

        if (attachmentsExists) {
            for (DataSource attachment : attachments) {
                BodyPart bodyPart = new MimeBodyPart();
                bodyPart.setDisposition(Part.ATTACHMENT);
                try {
                    bodyPart.setFileName(MimeUtility.encodeText(attachment.getName(), charset, null));
                } catch (UnsupportedEncodingException e) {
                    throw new FlowableMailException("Could not encode attachment file name", e);
                }
                bodyPart.setDataHandler(new DataHandler(attachment));
                rootContainer.addBodyPart(bodyPart);
            }
        }

        return rootContainer;
    }

    protected Session createSession() {
        if (serverConfiguration instanceof MailJndiServerConfiguration jndiServerConfiguration) {
            return createSession(jndiServerConfiguration);
        } else if (serverConfiguration instanceof MailHostServerConfiguration hostServerConfiguration) {
            return createSession(hostServerConfiguration);
        } else {
            throw new FlowableException("Unsupported server configuration " + serverConfiguration);
        }
    }

View on GitHub (pinned to d6d39ce1c6)