{"record":{"id":"da243992e530ef93","repo":"flowable/flowable-engine","slug":"when-using-email-headers-name-and-value-must-be-de","errorCode":null,"errorMessage":"When using email headers name and value must be defined colon separated. (e.g. X-Attribute: value","messagePattern":"When using email headers name and value must be defined colon separated\\. \\(e\\.g\\. X-Attribute: value","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/mail/BaseMailActivityDelegate.java","lineNumber":141,"sourceCode":"        message.setSubject(subjectStr);\n        message.setPlainContent(textStr);\n        message.setHtmlContent(htmlStr);\n        if (charSetStr != null) {\n            message.setCharset(Charset.forName(charSetStr));\n        }\n        addAttachments(message, variableContainer);\n\n        return message;\n    }\n\n    protected void addHeader(MailMessage message, String headersStr) {\n        if (headersStr == null) {\n            return;\n        }\n        for (String headerEntry : headersStr.split(NEWLINE_REGEX)) {\n            String[] split = headerEntry.split(\":\");\n            if (split.length != 2) {\n                throw new FlowableIllegalArgumentException(\"When using email headers name and value must be defined colon separated. (e.g. X-Attribute: value\");\n            }\n            String name = split[0].trim();\n            String value = split[1].trim();\n            message.addHeader(name, value);\n        }\n    }\n\n    protected void addAttachments(MailMessage message, V variableContainer) {\n        if (attachments == null) {\n            return;\n        }\n\n        Object value = attachments.getValue(variableContainer);\n        if (value == null) {\n            return;\n        }\n        if (value instanceof Collection<?> collection) {\n            if (!collection.isEmpty()) {","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/mail/BaseMailActivityDelegate.java#L123-L159","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nString headers = \"X-Attribute value\\nX-Priority: 1\";\n// after\nString headers = \"X-Attribute: value\\nX-Priority: 1\";","handlingStrategy":"validation","validationCode":"for (String line : headersStr.split(\"\\\\n\")) {\n    if (line.isBlank()) continue;\n    int idx = line.indexOf(':');\n    if (idx <= 0 || idx != line.lastIndexOf(':')) {\n        throw new IllegalArgumentException(\"Bad header (need exactly one colon): \" + line);\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    // send mail with headers\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"When using email headers\")) {\n        // sanitize/repair header string\n    }\n    throw e;\n}","preventionTips":["Build headers programmatically (name/value pairs) and serialize to 'name: value' lines","Never allow ':' inside header values","Test header strings after variable substitution"],"tags":["email","format","validation"],"backgroundTag":"invalid-argument-format","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}