flowable/flowable-engine · error · FlowableException

Could not send email: no SMTP host is configured

Error message

Could not send email: no SMTP host is configured

What it means

When the mail server configuration is host-based, createSession(MailHostServerConfiguration) first reads the SMTP host. If host() returns null, FlowableException "Could not send email: no SMTP host is configured" is thrown before any session properties are built. Sending email is impossible without a host.

Source

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

        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");

        properties.setProperty(MAIL_SMTP_SEND_PARTIAL, "false");
        properties.setProperty(MAIL_SMTPS_SEND_PARTIAL, "false");

        Authenticator authenticator = getAuthenticator(serverConfiguration);
        if (authenticator != null) {
            properties.setProperty(MAIL_SMTP_AUTH, "true");
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Set the SMTP host in the process engine configuration (mailServerHost, e.g. smtp.gmail.com)
  2. In Spring Boot, set flowable.mail.server.host (or flowable.mail.server.host property) in application properties
  3. If the value comes from an environment variable, verify it is present in the deployment environment
  4. If an app-server JNDI session is intended instead, configure MailJndiServerConfiguration rather than host config

Example fix

// before (flowable.cfg.xml)
<property name="mailServerPort" value="587" />
// after — host defined
<property name="mailServerHost" value="smtp.example.com" />
<property name="mailServerPort" value="587" />
Defensive patterns

Strategy: validation

Validate before calling

if (cfg instanceof MailHostServerConfiguration host && host.host() == null) {
    throw new IllegalArgumentException("mailServerHost is required for host-based mail configuration");
}

Try / catch

try {
    mailClient.send(mailMessage);
} catch (FlowableException e) {
    if (e.getMessage().contains("no SMTP host is configured")) {
        log.error("SMTP host missing; set mailServerHost in engine config");
    }
}

Prevention

When it happens

Trigger: Triggering any mail send (mail task or MailMessage send) with a MailHostServerConfiguration whose host was never set — e.g. engine configuration missing the mailServerHost property.

Common situations: Fresh Flowable install where default host 'localhost' was deliberately removed; properties file with a misspelled key so the host field stays null; environment-based config where the SMTP_HOST env var is absent in a container deployment; using JNDI-style config but the resolver produced a host-based one.

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/34f6510100cea6a7. Report an issue: GitHub.