{"record":{"id":"34f6510100cea6a7","repo":"flowable/flowable-engine","slug":"could-not-send-email-no-smtp-host-is-configured","errorCode":null,"errorMessage":"Could not send email: no SMTP host is configured","messagePattern":"Could not send email: no SMTP host is configured","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java","lineNumber":373,"sourceCode":"        try {\n            Context ctx;\n            if (sessionJndi.startsWith(\"java:\")) {\n                ctx = new InitialContext();\n            } else {\n                ctx = (Context) new InitialContext().lookup(\"java:comp/env\");\n\n            }\n\n            return (Session) ctx.lookup(sessionJndi);\n        } catch (NamingException e) {\n            throw new FlowableException(\"Could not send email: Incorrect JNDI configuration\", e);\n        }\n    }\n\n    protected Session createSession(MailHostServerConfiguration serverConfiguration) {\n        String host = serverConfiguration.host();\n        if (host == null) {\n            throw new FlowableException(\"Could not send email: no SMTP host is configured\");\n        }\n\n        Properties properties = new Properties(System.getProperties());\n        properties.setProperty(MAIL_TRANSPORT_PROTOCOL, \"smtp\");\n        properties.setProperty(MAIL_PORT, String.valueOf(serverConfiguration.port()));\n        properties.setProperty(MAIL_HOST, host);\n\n        MailHostServerConfiguration.Transport transport = serverConfiguration.transport();\n        properties.setProperty(MAIL_TRANSPORT_STARTTLS_ENABLE, Boolean.toString(serverConfiguration.isStartTlsEnabled()));\n        properties.setProperty(MAIL_TRANSPORT_STARTTLS_REQUIRED, \"false\");\n\n        properties.setProperty(MAIL_SMTP_SEND_PARTIAL, \"false\");\n        properties.setProperty(MAIL_SMTPS_SEND_PARTIAL, \"false\");\n\n        Authenticator authenticator = getAuthenticator(serverConfiguration);\n        if (authenticator != null) {\n            properties.setProperty(MAIL_SMTP_AUTH, \"true\");\n        }","sourceCodeStart":355,"sourceCodeEnd":391,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java#L355-L391","documentation":"When the mail server configuration is host-based, createSession(MailHostServerConfiguration) first reads the SMTP host. If host() returns null, FlowableException \"Could not send email: no SMTP host is configured\" is thrown before any session properties are built. Sending email is impossible without a host.","triggerScenarios":"Triggering any mail send (mail task or MailMessage send) with a MailHostServerConfiguration whose host was never set — e.g. engine configuration missing the mailServerHost property.","commonSituations":"Fresh Flowable install where default host 'localhost' was deliberately removed; properties file with a misspelled key so the host field stays null; environment-based config where the SMTP_HOST env var is absent in a container deployment; using JNDI-style config but the resolver produced a host-based one.","solutions":["Set the SMTP host in the process engine configuration (mailServerHost, e.g. smtp.gmail.com)","In Spring Boot, set flowable.mail.server.host (or flowable.mail.server.host property) in application properties","If the value comes from an environment variable, verify it is present in the deployment environment","If an app-server JNDI session is intended instead, configure MailJndiServerConfiguration rather than host config"],"exampleFix":"// before (flowable.cfg.xml)\n<property name=\"mailServerPort\" value=\"587\" />\n// after — host defined\n<property name=\"mailServerHost\" value=\"smtp.example.com\" />\n<property name=\"mailServerPort\" value=\"587\" />","handlingStrategy":"validation","validationCode":"if (cfg instanceof MailHostServerConfiguration host && host.host() == null) {\n    throw new IllegalArgumentException(\"mailServerHost is required for host-based mail configuration\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    mailClient.send(mailMessage);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"no SMTP host is configured\")) {\n        log.error(\"SMTP host missing; set mailServerHost in engine config\");\n    }\n}","preventionTips":["Always configure mailServerHost (or flowable.mail.server.host) before enabling mail tasks","Verify env-var-backed config resolves in every deployment environment","Fail fast with a startup validation of the mail configuration"],"tags":["mail","smtp","missing-config","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"}