{"record":{"id":"c8d61692c32d8442","repo":"flowable/flowable-engine","slug":"sessionjndi-has-to-be-set-for","errorCode":null,"errorMessage":"sessionJndi has to be set for ","messagePattern":"sessionJndi has to be set for ","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java","lineNumber":353,"sourceCode":"        }\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    }\n\n    protected Session createSession(MailJndiServerConfiguration serverConfiguration) {\n        String sessionJndi = serverConfiguration.getSessionJndi();\n        if (sessionJndi == null) {\n            throw new FlowableIllegalArgumentException(\"sessionJndi has to be set for \" + serverConfiguration);\n        }\n        try {\n            Context ctx;\n            if (sessionJndi.startsWith(\"java:\")) {\n                ctx = new InitialContext();\n            } else {\n                ctx = (Context) new InitialContext().lookup(\"java:comp/env\");\n\n            }\n\n            return (Session) ctx.lookup(sessionJndi);\n        } catch (NamingException e) {\n            throw new FlowableException(\"Could not send email: Incorrect JNDI configuration\", e);\n        }\n    }\n\n    protected Session createSession(MailHostServerConfiguration serverConfiguration) {\n        String host = serverConfiguration.host();","sourceCodeStart":335,"sourceCodeEnd":371,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java#L335-L371","documentation":"When the mail server configuration is a MailJndiServerConfiguration, createSession() requires sessionJndi to be non-null — it is the JNDI name under which the application server exposes the preconfigured mail Session. If it is null, FlowableIllegalArgumentException \"sessionJndi has to be set for <config>\" is thrown.","triggerScenarios":"Configuring mail with a JNDI server configuration (e.g. mailServerJndiName left empty in the process engine configuration) and then sending an email, so createSession(MailJndiServerConfiguration) finds sessionJndi == null.","commonSituations":"Deploying to WildFly/WebSphere/GlassFish where JNDI mail sessions are used, but the JNDI name property was never set in flowable.cfg.xml / Spring config; copy-pasting a host-based config into a JNDI environment without filling the JNDI name.","solutions":["Set the JNDI session name in the engine configuration (e.g. mailServerJndiName='java:comp/env/mail/Session')","Verify the mail session resource is declared in the app server (e.g. web.xml <resource-ref> + server config)","If no app-server session is intended, switch to MailHostServerConfiguration with explicit host/port instead"],"exampleFix":"// before (flowable.cfg.xml)\n<property name=\"mailServerUseCredentials\" value=\"true\" />\n// after — JNDI name configured\n<property name=\"mailServerJndiName\" value=\"java:comp/env/mail/Session\" />","handlingStrategy":"validation","validationCode":"if (cfg instanceof MailJndiServerConfiguration jndi && jndi.getSessionJndi() == null) {\n    throw new IllegalArgumentException(\"mailServerJndiName must be set for JNDI mail configuration\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    mailClient.send(mailMessage);\n} catch (FlowableIllegalArgumentException e) {\n    if (e.getMessage().startsWith(\"sessionJndi has to be set\")) {\n        log.error(\"JNDI mail config missing sessionJndi; check mailServerJndiName property\");\n    }\n}","preventionTips":["Set mailServerJndiName whenever JNDI mail mode is used","Validate engine configuration at startup, before the first mail send","Confirm the app server actually exposes the mail Session under that name"],"tags":["mail","jndi","missing-config","configuration"],"backgroundTag":"missing-required-config-field","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}