{"record":{"id":"ccd4cf98dbfbf369","repo":"flowable/flowable-engine","slug":"could-not-create-text-only-email","errorCode":null,"errorMessage":"Could not create text-only email","messagePattern":"Could not create text-only 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":264,"sourceCode":"            }\n        } catch (MessagingException e) {\n            throw new FlowableMailException(\"Failed to set send date\", e);\n        }\n    }\n\n    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","sourceCodeStart":246,"sourceCodeEnd":282,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java#L246-L282","documentation":"When the email is text-only (html is null and there are no attachments), setContent() calls mimeMessage.setText(text, charset). A MessagingException from setText is wrapped as FlowableMailException \"Could not create text-only email\". It means Jakarta Mail could not set the plain-text body on the freshly built MimeMessage.","triggerScenarios":"Sending a plain-text-only email (no html, no attachments) where MimeMessage.setText(text, charset) throws — typically due to an unsupported charset name or a MessagingException from the MIME part internals.","commonSituations":"Passing an invalid/unknown charset string (e.g. a typo like 'utf_8' or a localized name not recognized by the JDK); misconfigured mail server charset settings feeding an invalid charset into the mail task.","solutions":["Check the nested MessagingException cause for 'unsupported encoding' details","Validate the charset value passed via the mail task / MailMessage (use standard names: UTF-8, ISO-8859-1)","Ensure the JVM supports the charset (Charset.isSupported(charset))","Use html content instead of plain text if the charset issue persists"],"exampleFix":"// before\n<flowable:field name=\"text\">\n  <flowable:string>hello</flowable:string>\n</flowable:field>\n<flowable:field name=\"charSet\"><flowable:string>utf_8</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(\"Unsupported charset: \" + charset);\n}","typeGuard":null,"tryCatchPattern":"try {\n    mailClient.send(mailMessage);\n} catch (FlowableMailException e) {\n    if (e.getMessage().contains(\"Could not create text-only email\")) {\n        log.error(\"setText failed — check charset in mail config\", e.getCause());\n    }\n}","preventionTips":["Use canonical charset names (UTF-8, ISO-8859-1) in mail task config","Assert Charset.isSupported(charset) at startup","Prefer HTML content if charset edge cases keep occurring"],"tags":["mail","charset","text-email","messaging-exception"],"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"}