{"record":{"id":"e947152fed011bc3","repo":"flowable/flowable-engine","slug":"no-smtp-host-is-configured-for-the-default-mail-se-e94715","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/flowable5-engine/src/main/java/org/activiti/engine/impl/cfg/ProcessEngineConfigurationImpl.java","lineNumber":1465,"sourceCode":"        }\n    }\n\n    protected void initExpressionManager() {\n        if (expressionManager == null) {\n            expressionManager = new ExpressionManager(beans);\n        }\n    }\n\n    public void initMailClients() {\n        if (defaultMailClient == null) {\n            String sessionJndi = getMailSessionJndi();\n            if (sessionJndi != null) {\n                defaultMailClient = 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                defaultMailClient = 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            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) {\n                    mailClients.put(tenantId, FlowableMailClientCreator.createSessionClient(sessionJndi, tenantMailServer, defaultMailServer));","sourceCodeStart":1447,"sourceCodeEnd":1483,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cfg/ProcessEngineConfigurationImpl.java#L1447-L1483","documentation":"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.","triggerScenarios":"Calling ProcessEngineConfigurationImpl.buildProcessEngine() (which triggers mail client init via getDefaultMailServer/FlowableMailClientCreator) when mailServerHost was never set and no mail session JNDI name is configured.","commonSituations":"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.","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"],"exampleFix":"// before\nProcessEngineConfiguration cfg = ProcessEngineConfiguration.createProcessEngineConfigurationFromResourceDefault();\n// after\nProcessEngineConfiguration cfg = ProcessEngineConfiguration.createProcessEngineConfigurationFromResourceDefault();\ncfg.setMailServerHost(\"smtp.example.com\");\ncfg.setMailServerPort(587);","handlingStrategy":"validation","validationCode":"MailServerInfo mailServer = processEngineConfiguration.getDefaultMailServer();\nif (mailServer == null || mailServer.getMailServerHost() == null || mailServer.getMailServerHost().isEmpty()) {\n    throw new IllegalStateException(\"flowable.mail.server.host must be set before building the engine\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["configuration","smtp","mail","startup"],"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-18T11:17:12.947Z"}