flowable/flowable-engine · error · FlowableException

msg

Error message

msg

What it means

When sending the mail fails and no exceptionVariableName field is configured, handleException wraps the failure in a FlowableException whose message is the underlying mail failure message ('msg'). The original exception is attached as the cause if it was a FlowableMailException; otherwise it is rethrown as-is. This is the generic wrapping point for mail send failures.

Solutions

1. Inspect the cause of the FlowableException for the real SMTP error (connection refused, auth failed, etc.)
2. Verify mailServer configuration (host, port, username, password, useTLS) in the engine configuration
3. Optionally set the 'exceptionVariableName' field on the mail task to capture failures into a process variable instead of throwing

Example fix

// before (engine config missing mail server)
processEngineConfiguration.setMailServerHost(null);
// after
processEngineConfiguration.setMailServerHost("smtp.example.com");
processEngineConfiguration.setMailServerPort(587);
processEngineConfiguration.setMailServerUseTLS(true);

// verify SMTP reachability/config before sending
InetAddress.getByName(mailServerHost); // throws if host unresolvable

try {
    // execute mail task
} catch (FlowableException e) {
    Throwable cause = e.getCause();
    log.error("Mail send failed: {} cause: {}", e.getMessage(), cause, cause);
    // inspect cause: SMTPAddressFailedException, AuthenticationFailedException, etc.
}

When it happens

Trigger: Any mail send failure (SMTP connection failure, authentication error, bad address, TLS problem) occurring in prepareAndExecuteRequest when the mail activity does not define an 'exceptionVariableName' field to capture errors into a variable.

Common situations: SMTP server unreachable/wrong host-port, bad credentials, refused relay, invalid recipient addresses; misconfigured mailServer settings in the engine configuration.

Related errors

• Sending the email to the following server failed :
• Could not execute inner activity behavior of multi instance…
• Could not send email: no SMTP host is configured
• couldn't execute activity <
• couldn't execute event listener :

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/c935c8573f5b28fe. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/mail/BaseMailActivityDelegate.java:251

        return file != null && file.exists() && file.isFile() && file.canRead();
    }

    protected Expression getExpression(V variableContainer, Expression var) {
        String variable = (String) variableContainer.getVariable(var.getExpressionText());
        return createExpression(variable);
    }

    protected void handleException(V variableContainer, String msg, FlowableException e) {
        boolean doIgnoreException = Boolean.parseBoolean(getStringFromField(ignoreException, variableContainer));
        if (doIgnoreException) {
            logger.info("Ignoring email send error: {}", msg, e);
            String exceptionVariable = getStringFromField(exceptionVariableName, variableContainer);
            if (exceptionVariable != null && exceptionVariable.length() > 0) {
                variableContainer.setVariable(exceptionVariable, msg);
            }
        } else {
            if (e instanceof FlowableMailException) {
                throw new FlowableException(msg, e);
            } else {
                throw e;
            }
        }
    }

    public static class ContentItemDataSourceWrapper implements DataSource {

        protected final ContentItem contentItem;
        protected final ContentService contentService;

        public ContentItemDataSourceWrapper(ContentItem contentItem, ContentService contentService) {
            this.contentItem = contentItem;
            this.contentService = contentService;
        }

        @Override
        public InputStream getInputStream() throws IOException {

View on GitHub (pinned to d6d39ce1c6)