{"record":{"id":"39ea913f724706a6","repo":"flowable/flowable-engine","slug":"no-smtp-host-is-configured-for-the-default-mail-se-39ea91","errorCode":null,"errorMessage":"no SMTP host is configured for the default mail server","messagePattern":"no SMTP host is configured for the default mail server","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cfg/ProcessEngineConfigurationImpl.java","lineNumber":2387,"sourceCode":"        expressionManager.setAstFunctionCreators(astFunctionCreators);\n    }\n\n    public void initMailClients() {\n        if (mailClientProvider == null) {\n            mailClientProvider = new DefaultMailClientProvider();\n        }\n        if (!(mailClientProvider instanceof DefaultMailClientProvider defaultMailClientProvider)) {\n            return; // custom provider handles resolution at runtime\n        }\n        if (defaultMailClientProvider.getDefaultMailClient() == null) {\n            String sessionJndi = getMailSessionJndi();\n            if (sessionJndi != null) {\n                defaultMailClientProvider.setDefaultMailClient(FlowableMailClientCreator.createSessionClient(sessionJndi, getDefaultMailServer()));\n            } else {\n                MailServerInfo mailServer = getDefaultMailServer();\n                String host = mailServer.getMailServerHost();\n                if (host == null) {\n                    throw new FlowableException(\"no SMTP host is configured for the default mail server\");\n                }\n                defaultMailClientProvider.setDefaultMailClient(FlowableMailClientCreator.createHostClient(host, mailServer));\n            }\n        }\n\n        Collection<String> tenantIds = new HashSet<>(mailSessionsJndi.keySet());\n        tenantIds.addAll(mailServers.keySet());\n\n        if (!tenantIds.isEmpty()) {\n            Map<String, FlowableMailClient> mailClients = defaultMailClientProvider.getMailClients();\n            MailServerInfo defaultMailServer = getDefaultMailServer();\n            for (String tenantId : tenantIds) {\n                if (mailClients.containsKey(tenantId)) {\n                    continue;\n                }\n                String sessionJndi = mailSessionsJndi.get(tenantId);\n                MailServerInfo tenantMailServer = mailServers.get(tenantId);\n                if (sessionJndi != null) {","sourceCodeStart":2369,"sourceCodeEnd":2405,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cfg/ProcessEngineConfigurationImpl.java#L2369-L2405","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nprocessEngineConfiguration.setMailServerPort(1025);\n// after\nprocessEngineConfiguration.setMailServerHost(\"smtp.example.com\");\nprocessEngineConfiguration.setMailServerPort(1025);","handlingStrategy":"validation","validationCode":"if (processEngineConfiguration.getMailServerHost() == null || processEngineConfiguration.getMailServerHost().isEmpty()) {\n    processEngineConfiguration.setMailServerHost(\"smtp.example.com\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["flowable","configuration","smtp","mail"],"backgroundTag":"missing-required-config-field","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}