What causes "no SMTP host is configured for the default mail server" in flowable/flowable-engine?

Set the default mail server host, e.g. processEngineConfiguration.setMailServerHost("smtp.example.com") or set flowable.mail.server.host=smtp.example.com

flowable/flowable-engine · error · FlowableException

no SMTP host is configured for the default mail server

Error message

no SMTP host is configured for the default mail server

What it means

Flowable's process engine configures mail clients at startup from MailServerInfo settings. When building the default mail client, if no JNDI mail session is configured and mailServerHost is null, the engine cannot create an SMTP client and throws this FlowableException during configuration initialization.

Solutions

Set the default mail server host, e.g. processEngineConfiguration.setMailServerHost("smtp.example.com") or set flowable.mail.server.host=smtp.example.com
If using an application-server-managed session, configure mailSessionJndi (setMailSessionJndi("mail/Session")) instead of host/port credentials
Verify the Spring/properties wiring actually reaches the engine config (correct property prefix, loaded file)
If mail is never used, ensure host defaults or disable mail task usage to avoid the check at startup

Example fix

// before
ProcessEngineConfiguration cfg = ProcessEngineConfiguration.createProcessEngineConfigurationFromResourceDefault();
// after
ProcessEngineConfiguration cfg = ProcessEngineConfiguration.createProcessEngineConfigurationFromResourceDefault();
cfg.setMailServerHost("smtp.example.com");
cfg.setMailServerPort(587);

Defensive patterns

Strategy: validation

Validate before calling

MailServerInfo mailServer = processEngineConfiguration.getDefaultMailServer();
if (mailServer == null || mailServer.getMailServerHost() == null || mailServer.getMailServerHost().isEmpty()) {
    throw new IllegalStateException("flowable.mail.server.host must be set before building the engine");
}

Prevention

Always set mailServerHost (or the JNDI session name) in engine configuration before buildProcessEngine()
Externalize mail settings into application properties and validate them at startup with a fail-fast check
Add a unit/integration test that builds the engine config and asserts mail host presence
When upgrading Flowable versions, diff property names — renamed mail properties silently become null

When it happens

Trigger: Calling ProcessEngineConfigurationImpl.buildProcessEngine() (which triggers mail client init via getDefaultMailServer/FlowableMailClientCreator) when mailServerHost was never set and no mail session JNDI name is configured.

Common situations: Deploying an app that uses mail tasks without setting mailServerHost (or the flowable.mail.server.host property); a properties file missing the host key; a config refactor renaming the property so the value silently becomes null.

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cfg/ProcessEngineConfigurationImpl.java:1465

        }
    }

    protected void initExpressionManager() {
        if (expressionManager == null) {
            expressionManager = new ExpressionManager(beans);
        }
    }

    public void initMailClients() {
        if (defaultMailClient == null) {
            String sessionJndi = getMailSessionJndi();
            if (sessionJndi != null) {
                defaultMailClient = FlowableMailClientCreator.createSessionClient(sessionJndi, getDefaultMailServer());
            } else {
                MailServerInfo mailServer = getDefaultMailServer();
                String host = mailServer.getMailServerHost();
                if (host == null) {
                    throw new FlowableException("no SMTP host is configured for the default mail server");
                }
                defaultMailClient = FlowableMailClientCreator.createHostClient(host, mailServer);
            }
        }

        Collection<String> tenantIds = new HashSet<>(mailSessionsJndi.keySet());
        tenantIds.addAll(mailServers.keySet());

        if (!tenantIds.isEmpty()) {
            MailServerInfo defaultMailServer = getDefaultMailServer();
            for (String tenantId : tenantIds) {
                if (mailClients.containsKey(tenantId)) {
                    continue;
                }
                String sessionJndi = mailSessionsJndi.get(tenantId);
                MailServerInfo tenantMailServer = mailServers.get(tenantId);
                if (sessionJndi != null) {
                    mailClients.put(tenantId, FlowableMailClientCreator.createSessionClient(sessionJndi, tenantMailServer, defaultMailServer));

View on GitHub (pinned to d6d39ce1c6)