{"record":{"id":"b923734dcf2eb94f","repo":"flowable/flowable-engine","slug":"could-not-encode-attachment-file-name","errorCode":null,"errorMessage":"Could not encode attachment file name","messagePattern":"Could not encode attachment file name","errorType":"exception","errorClass":"FlowableMailException","httpStatus":null,"severity":"error","filePath":"modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java","lineNumber":330,"sourceCode":"                    msgHtml.setContent(html, CONTENT_TYPE_TEXT_HTML);\n                }\n            }\n        }\n\n        if (StringUtils.isNotEmpty(text)) {\n            MimeBodyPart msgText = new MimeBodyPart();\n            bodyContainer.addBodyPart(msgText, 0);\n            msgText.setText(text, charset);\n        }\n\n        if (attachmentsExists) {\n            for (DataSource attachment : attachments) {\n                BodyPart bodyPart = new MimeBodyPart();\n                bodyPart.setDisposition(Part.ATTACHMENT);\n                try {\n                    bodyPart.setFileName(MimeUtility.encodeText(attachment.getName(), charset, null));\n                } catch (UnsupportedEncodingException e) {\n                    throw new FlowableMailException(\"Could not encode attachment file name\", e);\n                }\n                bodyPart.setDataHandler(new DataHandler(attachment));\n                rootContainer.addBodyPart(bodyPart);\n            }\n        }\n\n        return rootContainer;\n    }\n\n    protected Session createSession() {\n        if (serverConfiguration instanceof MailJndiServerConfiguration jndiServerConfiguration) {\n            return createSession(jndiServerConfiguration);\n        } else if (serverConfiguration instanceof MailHostServerConfiguration hostServerConfiguration) {\n            return createSession(hostServerConfiguration);\n        } else {\n            throw new FlowableException(\"Unsupported server configuration \" + serverConfiguration);\n        }\n    }","sourceCodeStart":312,"sourceCodeEnd":348,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java#L312-L348","documentation":"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\".","triggerScenarios":"Sending an email with attachments where the configured charset is not recognized by the JVM's Jakarta Mail MimeUtility, causing UnsupportedEncodingException during bodyPart.setFileName(...).","commonSituations":"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.","solutions":["Check the nested UnsupportedEncodingException for the offending charset name","Set the mail task charSet to a standard supported value like UTF-8","Verify with Charset.isSupported(charset) before sending","Ensure the JVM's full charset set is available (not a reduced/compact runtime)"],"exampleFix":"// before\n<flowable:field name=\"charSet\"><flowable:string>ISO-8859</flowable:string></flowable:field>\n// after\n<flowable:field name=\"charSet\"><flowable:string>UTF-8</flowable:string></flowable:field>","handlingStrategy":"validation","validationCode":"if (charset != null && !java.nio.charset.Charset.isSupported(charset)) {\n    throw new IllegalArgumentException(\"Cannot MIME-encode attachments with charset: \" + charset);\n}","typeGuard":null,"tryCatchPattern":"try {\n    mailClient.send(mailMessage);\n} catch (FlowableMailException e) {\n    if (e.getMessage().contains(\"Could not encode attachment file name\")) {\n        log.error(\"Attachment filename encoding failed; fix configured charset\", e.getCause());\n    }\n}","preventionTips":["Configure a universally supported charset (UTF-8) for mail","Sanitize attachment file names to ASCII where possible","Verify charset support on the target JVM/runtime image"],"tags":["mail","charset","attachment","encoding"],"backgroundTag":"invalid-argument-value","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}