{"record":{"id":"52cdc687e3ae4d5e","repo":"flowable/flowable-engine","slug":"failed-to-create-multi-part-email","errorCode":null,"errorMessage":"Failed to create multi part email","messagePattern":"Failed to create multi part email","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":270,"sourceCode":"    protected void setContent(MimeMessage mimeMessage, MailMessage message, String charset) {\n        String text = message.getPlainContent();\n        String html = message.getHtmlContent();\n        Collection<DataSource> attachments = message.getAttachments();\n        boolean attachmentsExists = attachments != null && !attachments.isEmpty();\n        if (html == null && text == null) {\n            throw new FlowableIllegalArgumentException(\"'html' or 'text' is required to be defined when sending an email\");\n        }\n        if (html == null && !attachmentsExists) {\n            try {\n                mimeMessage.setText(text, charset);\n            } catch (MessagingException e) {\n                throw new FlowableMailException(\"Could not create text-only email\", e);\n            }\n        } else {\n            try {\n                mimeMessage.setContent(createMultiPartContent(text, html, charset, attachments));\n            } catch (MessagingException e) {\n                throw new FlowableMailException(\"Failed to create multi part email\", e);\n            }\n        }\n    }\n\n    protected MimeMultipart createMultiPartContent(String text, String html, String charset, Collection<DataSource> attachments) throws MessagingException {\n        boolean attachmentsExists = attachments != null && !attachments.isEmpty();\n\n        MimeMultipart rootContainer = new MimeMultipart();\n        MimeMultipart bodyContainer = rootContainer;\n\n        rootContainer.setSubType(\"mixed\");\n\n        if (StringUtils.isNotEmpty(text) && StringUtils.isNotEmpty(html)) {\n            if (attachmentsExists) {\n                // If both HTML and TEXT bodies are provided, create an alternative\n                // container and add it to the root container\n                bodyContainer = new MimeMultipart(\"alternative\");\n                MimeBodyPart bodyPart = new MimeBodyPart();","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java#L252-L288","documentation":"For emails that are not text-only (html present or attachments present), setContent() builds content via createMultiPartContent and assigns it with mimeMessage.setContent(...). A MessagingException from that call is wrapped as FlowableMailException \"Failed to create multi part email\". It indicates the MIME multipart structure could not be attached to the message.","triggerScenarios":"Sending an HTML email (optionally with attachments) where mimeMessage.setContent(multipart) or the internal multipart assembly throws MessagingException — e.g. corrupted part structure or provider failure.","commonSituations":"Large or malformed attachments failing during DataHandler wiring; Jakarta Mail provider incompatibilities; mixing incompatible jakarta.mail versions where multipart handling differs.","solutions":["Inspect the nested MessagingException cause for the failing MIME part","Verify attachment DataSources are readable and have valid names/content types","Ensure a single consistent jakarta.mail implementation is on the classpath","Test with a minimal HTML-only email to isolate whether attachments are the cause"],"exampleFix":"// before: custom DataSource returning null content type\nnew DataSource() { public String getContentType() { return null; } ... }\n// after\nnew DataSource() { public String getContentType() { return \"application/octet-stream\"; } ... }","handlingStrategy":"try-catch","validationCode":"attachments.forEach(a -> {\n    if (a.getContentType() == null || a.getName() == null)\n        throw new IllegalArgumentException(\"Attachment missing name/content-type\");\n});","typeGuard":null,"tryCatchPattern":"try {\n    mailClient.send(mailMessage);\n} catch (FlowableMailException e) {\n    if (e.getMessage().contains(\"Failed to create multi part email\")) {\n        log.error(\"Multipart assembly failed; check attachments and jakarta.mail version\", e.getCause());\n    }\n}","preventionTips":["Give every attachment DataSource a valid name and content type","Avoid mixing javax.mail and jakarta.mail artifacts","Smoke-test HTML+attachment sends after upgrading Flowable"],"tags":["mail","multipart","html-email","messaging-exception"],"backgroundTag":"api-request-failed","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"}