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

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 eagerly initializes a default mail client at configuration time. If mail is being set up (mail server config present / JNDI path taken) but no mailServerHost was supplied, it throws this FlowableException during engine build. It is a fail-fast configuration validation so mail-send activities do not fail later at runtime.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cfg/ProcessEngineConfigurationImpl.java:2387

        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 default mail server host, e.g. processEngineConfiguration.setMailServerHost("smtp.example.com") or spring.flowable.mail-server-host in properties.
If email tasks are not needed, ensure a valid host is set anyway or disable/remove the mail server configuration so no mail client is initialized.
If using JNDI, configure mailServerJndi so the session client path is used instead of the host path.

Example fix

// before
processEngineConfiguration.setMailServerPort(1025);
// after
processEngineConfiguration.setMailServerHost("smtp.example.com");
processEngineConfiguration.setMailServerPort(1025);

Defensive patterns

Strategy: validation

Validate before calling

if (processEngineConfiguration.getMailServerHost() == null || processEngineConfiguration.getMailServerHost().isEmpty()) {
    processEngineConfiguration.setMailServerHost("smtp.example.com");
}

Prevention

Always set mailServerHost when any mail configuration property is present
Keep SMTP settings in one validated config class loaded at startup
Smoke-test engine build in CI with the real mail config

When it happens

Trigger: ProcessEngineConfigurationImpl initialization (initMailClient path) when defaultMailServer.getMailServerHost() returns null — e.g. a MailServerInfo/DefaultMailServer configured with only useCredentials/port set and host missing, or a default mail server entry created without a host.

Common situations: Missing flowable.mail-server-host (or mailServerHost in Spring Boot properties) while enabling mail; copying a config template and leaving host blank; enabling mail tasks without intending to use email and leaving an empty default mail server configured.

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