{"record":{"id":"c7d1bc666c3487b3","repo":"flowable/flowable-engine","slug":"header-value-cannot-be-null-or-empty","errorCode":null,"errorMessage":"header value cannot be null or empty","messagePattern":"header value cannot be null or empty","errorType":"validation","errorClass":"FlowableMailException","httpStatus":null,"severity":"error","filePath":"modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java","lineNumber":155,"sourceCode":"            } else {\n                message.setSubject(subject);\n            }\n        }\n    }\n\n    protected void addHeaders(MimeMessage message, Map<String, String> headers, Charset charset) throws MessagingException {\n        if (headers != null && !headers.isEmpty()) {\n            for (Map.Entry<String, String> entry : headers.entrySet()) {\n\n                String name = entry.getKey();\n                String value = entry.getValue();\n\n                if (StringUtils.isEmpty(name)) {\n                    throw new FlowableMailException(\"header name cannot be null or empty\");\n                }\n\n                if (StringUtils.isEmpty(value)) {\n                    throw new FlowableMailException(\"header value cannot be null or empty\");\n                }\n\n                String foldedHeaderValue = createFoldedHeaderValue(name, value, charset);\n                message.addHeader(name, foldedHeaderValue);\n            }\n        }\n\n    }\n\n    protected String createFoldedHeaderValue(String name, String value, Charset charset) {\n        try {\n            return MimeUtility.fold(name.length() + 2, MimeUtility.encodeText(value, charset != null ? charset.name() : null, null));\n        } catch (UnsupportedEncodingException e) {\n            return value;\n        }\n    }\n\n    protected void addTo(MimeMessage message, Collection<String> to) {","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java#L137-L173","documentation":"In addHeaders, after validating the header name, the client also rejects entries whose value is null or empty, throwing FlowableMailException. A header with no value is not meaningful for mail transport, so the library refuses to add it rather than sending a malformed message.","triggerScenarios":"Passing a SendMailRequest whose extraHeaders map contains an entry with an empty-string or null value, e.g. headers where the value was optional and defaulted to nothing.","commonSituations":"Building headers from configuration where the value key is missing; templates that substitute empty variables into header values; empty tracking or metadata headers produced by upstream systems.","solutions":["Remove or skip header entries with null/empty values before constructing the request.","Provide a real default value for optional headers instead of an empty string.","Validate the headers map in application code before sending."],"exampleFix":"// before\nheaders.put(\"X-Campaign\", campaignId); // campaignId may be \"\"\n\n// after\nif (campaignId != null && !campaignId.isEmpty()) {\n    headers.put(\"X-Campaign\", campaignId);\n}","handlingStrategy":"validation","validationCode":"Map<String,String> safeHeaders = headers.entrySet().stream()\n    .filter(e -> e.getValue() != null && !e.getValue().trim().isEmpty())\n    .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue));","typeGuard":"boolean hasValuedHeaders(Map<String,String> h) { return h.values().stream().allMatch(v -> v != null && !v.isBlank()); }","tryCatchPattern":"try { client.sendMail(request); } catch (FlowableMailException e) { if (e.getMessage().contains(\"header value\")) { log.warn(\"empty header value in request\"); } throw e; }","preventionTips":["Skip optional headers entirely instead of setting them to empty strings.","Provide default values for template-substituted header content.","Validate header maps in a shared mail-request builder."],"tags":["mail","headers","validation","jakarta-mail"],"backgroundTag":"empty-required-field","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"}