flowable/flowable-engine · error · FlowableException

Could not send email: Incorrect JNDI configuration

Error message

Could not send email: Incorrect JNDI configuration

What it means

For a JNDI mail configuration, createSession() performs ctx.lookup(sessionJndi) to fetch the jakarta.mail Session. Any NamingException — the name does not exist, is not bound to a Session, or the InitialContext itself fails — is wrapped as FlowableException "Could not send email: Incorrect JNDI configuration".

Source

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

    }

    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();
        if (host == null) {
            throw new FlowableException("Could not send email: no SMTP host is configured");
        }

        Properties properties = new Properties(System.getProperties());
        properties.setProperty(MAIL_TRANSPORT_PROTOCOL, "smtp");
        properties.setProperty(MAIL_PORT, String.valueOf(serverConfiguration.port()));
        properties.setProperty(MAIL_HOST, host);

        MailHostServerConfiguration.Transport transport = serverConfiguration.transport();
        properties.setProperty(MAIL_TRANSPORT_STARTTLS_ENABLE, Boolean.toString(serverConfiguration.isStartTlsEnabled()));
        properties.setProperty(MAIL_TRANSPORT_STARTTLS_REQUIRED, "false");

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Verify the exact JNDI name as bound by the app server (check server startup logs / admin console)
  2. Declare a <resource-ref> for the mail session in web.xml and map it in the deployment descriptor
  3. Confirm the bound object is a jakarta.mail.Session (not javax.mail.Session — version mismatch)
  4. Test the lookup manually with a small servlet or by listing the JNDI tree

Example fix

// before
<property name="mailServerJndiName" value="mail/MySession" />
// after — fully qualified, matching server binding and resource-ref
<property name="mailServerJndiName" value="java:comp/env/mail/MySession" />
Defensive patterns

Strategy: try-catch

Validate before calling

try {
    new InitialContext().lookup(sessionJndi);
} catch (NamingException e) {
    throw new IllegalStateException("Mail session not bound at " + sessionJndi, e);
}

Try / catch

try {
    mailClient.send(mailMessage);
} catch (FlowableException e) {
    if (e.getMessage().contains("Incorrect JNDI configuration")) {
        log.error("JNDI lookup failed for mail session; verify binding and resource-ref", e.getCause());
    }
}

Prevention

When it happens

Trigger: Sending email with MailJndiServerConfiguration where lookup(sessionJndi) throws NamingException: wrong JNDI name, session resource not deployed, missing 'java:' prefix handling, or missing resource-ref mapping in the web module.

Common situations: Typo in the JNDI name (mail/session vs mail/Session); mail resource defined in the app server but no <resource-ref> in web.xml so 'java:comp/env/mail/Session' is unbound; deploying the same WAR on a server without the mail resource; wrong naming context for non-'java:' names.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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