flowable/flowable-engine · error · FlowableIllegalArgumentException

sessionJndi has to be set for

Error message

sessionJndi has to be set for

What it means

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.

Source

Thrown at modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java:353

        }

        return rootContainer;
    }

    protected Session createSession() {
        if (serverConfiguration instanceof MailJndiServerConfiguration jndiServerConfiguration) {
            return createSession(jndiServerConfiguration);
        } else if (serverConfiguration instanceof MailHostServerConfiguration hostServerConfiguration) {
            return createSession(hostServerConfiguration);
        } else {
            throw new FlowableException("Unsupported server configuration " + serverConfiguration);
        }
    }

    protected Session createSession(MailJndiServerConfiguration serverConfiguration) {
        String sessionJndi = serverConfiguration.getSessionJndi();
        if (sessionJndi == null) {
            throw new FlowableIllegalArgumentException("sessionJndi has to be set for " + serverConfiguration);
        }
        try {
            Context ctx;
            if (sessionJndi.startsWith("java:")) {
                ctx = new InitialContext();
            } else {
                ctx = (Context) new InitialContext().lookup("java:comp/env");

            }

            return (Session) ctx.lookup(sessionJndi);
        } catch (NamingException e) {
            throw new FlowableException("Could not send email: Incorrect JNDI configuration", e);
        }
    }

    protected Session createSession(MailHostServerConfiguration serverConfiguration) {
        String host = serverConfiguration.host();

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Set the JNDI session name in the engine configuration (e.g. mailServerJndiName='java:comp/env/mail/Session')
  2. Verify the mail session resource is declared in the app server (e.g. web.xml <resource-ref> + server config)
  3. If no app-server session is intended, switch to MailHostServerConfiguration with explicit host/port instead

Example fix

// before (flowable.cfg.xml)
<property name="mailServerUseCredentials" value="true" />
// after — JNDI name configured
<property name="mailServerJndiName" value="java:comp/env/mail/Session" />
Defensive patterns

Strategy: validation

Validate before calling

if (cfg instanceof MailJndiServerConfiguration jndi && jndi.getSessionJndi() == null) {
    throw new IllegalArgumentException("mailServerJndiName must be set for JNDI mail configuration");
}

Try / catch

try {
    mailClient.send(mailMessage);
} catch (FlowableIllegalArgumentException e) {
    if (e.getMessage().startsWith("sessionJndi has to be set")) {
        log.error("JNDI mail config missing sessionJndi; check mailServerJndiName property");
    }
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/c8d61692c32d8442. Report an issue: GitHub.