{"record":{"id":"5c90092340b94c8f","repo":"flowable/flowable-engine","slug":"no-smtp-host-is-configured-for-the-default-mail-se","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-cmmn-engine/src/main/java/org/flowable/cmmn/engine/CmmnEngineConfiguration.java","lineNumber":959,"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":941,"sourceCodeEnd":977,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/CmmnEngineConfiguration.java#L941-L977","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)"],"exampleFix":"// before\nCmmnEngineConfiguration cfg = new CmmnEngineConfiguration();\n\n// after\ncfg.setMailServerHost(\"smtp.example.com\");\ncfg.setMailServerPort(587);\ncfg.setMailServerUseTLS(true);","handlingStrategy":"validation","validationCode":"if (cmmnEngineConfiguration.getMailServerHost() == null\n        || cmmnEngineConfiguration.getMailServerHost().isEmpty()) {\n    throw new IllegalStateException(\"Configure flowable.mail.server.host before starting the CMMN engine\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["cmmn","mail","smtp","configuration"],"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"}