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

Set the SMTP host: cmmnEngineConfiguration.setMailServerHost("smtp.example.com") or add flowable.mail.server.host to config

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

Thrown during CmmnEngineConfiguration mail client initialization when the default mail server has no SMTP host configured. Flowable builds a mail client from mailServerHost/port/credentials at engine startup and refuses to start the mail infrastructure with a null host.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/CmmnEngineConfiguration.java:959

        expressionManager.setAstFunctionCreators(astFunctionCreators);
    }

    public void initMailClients() {
        if (mailClientProvider == null) {
            mailClientProvider = new DefaultMailClientProvider();
        }
        if (!(mailClientProvider instanceof DefaultMailClientProvider defaultMailClientProvider)) {
            return; // custom provider handles resolution at runtime
        }
        if (defaultMailClientProvider.getDefaultMailClient() == null) {
            String sessionJndi = getMailSessionJndi();
            if (sessionJndi != null) {
                defaultMailClientProvider.setDefaultMailClient(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");
                }
                defaultMailClientProvider.setDefaultMailClient(FlowableMailClientCreator.createHostClient(host, mailServer));
            }
        }

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

        if (!tenantIds.isEmpty()) {
            Map<String, FlowableMailClient> mailClients = defaultMailClientProvider.getMailClients();
            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) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

Set the SMTP host: cmmnEngineConfiguration.setMailServerHost("smtp.example.com") or add flowable.mail.server.host to config
If using JNDI, ensure mailSessionJndi is set so a host is not required
Disable mail support explicitly (setMailServerHost to empty or use setMailClientProvider with a custom provider) if email is not used
Verify the properties file actually reaches the engine configuration (correct cfg.xml on classpath)

Example fix

// before
CmmnEngineConfiguration cfg = new CmmnEngineConfiguration();

// after
cfg.setMailServerHost("smtp.example.com");
cfg.setMailServerPort(587);
cfg.setMailServerUseTLS(true);

Defensive patterns

Strategy: validation

Validate before calling

if (cmmnEngineConfiguration.getMailServerHost() == null
        || cmmnEngineConfiguration.getMailServerHost().isEmpty()) {
    throw new IllegalStateException("Configure flowable.mail.server.host before starting the CMMN engine");
}

Prevention

Externalize SMTP host config and fail fast at app startup with a clear message
Use JNDI mail sessions in app-server deployments
Disable/omit mail configuration if the engine never sends mail
Add a smoke test that boots the engine with production config

When it happens

Trigger: Engine configuration with mail server enabled (or default settings active) where cmmnEngineConfiguration.getMailServerHost() / MailServerInfo.mailServerHost is null — e.g. no 'flowable.mail.server.host' property set and no JNDI session configured.

Common situations: Fresh deployment missing SMTP properties in flowable.cmmn.cfg.xml / Spring properties; copying config that sets user/password but forgot host; environment variable for SMTP host not injected in container; typo in property key.

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