flowable/flowable-engine · error · FlowableException

Unsupported server configuration

Error message

Unsupported server configuration

What it means

createSession() dispatches on the type of the configured serverConfiguration: it supports MailJndiServerConfiguration and MailHostServerConfiguration. Any other implementation type reaches the else branch and throws FlowableException "Unsupported server configuration <config>". The message conveniently echoes the object via toString().

Source

Thrown at modules/flowable-mail/src/main/java/org/flowable/mail/common/impl/jakarta/mail/JakartaMailFlowableMailClient.java:346

                    bodyPart.setFileName(MimeUtility.encodeText(attachment.getName(), charset, null));
                } catch (UnsupportedEncodingException e) {
                    throw new FlowableMailException("Could not encode attachment file name", e);
                }
                bodyPart.setDataHandler(new DataHandler(attachment));
                rootContainer.addBodyPart(bodyPart);
            }
        }

        return rootContainer;
    }

    protected Session createSession() {
        if (serverConfiguration instanceof MailJndiServerConfiguration jndiServerConfiguration) {
            return createSession(jndiServerConfiguration);
        } else if (serverConfiguration instanceof MailHostServerConfiguration hostServerConfiguration) {
            return createSession(hostServerConfiguration);
        } else {
            throw new FlowableException("Unsupported server configuration " + serverConfiguration);
        }
    }

    protected Session createSession(MailJndiServerConfiguration serverConfiguration) {
        String sessionJndi = serverConfiguration.getSessionJndi();
        if (sessionJndi == null) {
            throw new FlowableIllegalArgumentException("sessionJndi has to be set for " + serverConfiguration);
        }
        try {
            Context ctx;
            if (sessionJndi.startsWith("java:")) {
                ctx = new InitialContext();
            } else {
                ctx = (Context) new InitialContext().lookup("java:comp/env");

            }

            return (Session) ctx.lookup(sessionJndi);

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Log/print the configuration object class to see what was actually injected
  2. Use MailHostServerConfiguration (host/port/credentials) for standard SMTP setups
  3. Use MailJndiServerConfiguration when the mail session comes from JNDI
  4. Make custom configurations extend one of the two supported classes instead of implementing the interface directly

Example fix

// before
ServerConfiguration cfg = new MyCustomMailConfig();
// after
MailHostServerConfiguration cfg = new MailHostServerConfiguration(
    "smtp.example.com", 587, "user", "pass", true, false, null);
mailClient.setServerConfiguration(cfg);
Defensive patterns

Strategy: type-guard

Validate before calling

if (!(serverConfiguration instanceof MailJndiServerConfiguration)
        && !(serverConfiguration instanceof MailHostServerConfiguration)) {
    throw new IllegalArgumentException(
        "ServerConfiguration must be MailJndi or MailHost: " + serverConfiguration.getClass());
}

Type guard

boolean isSupportedConfig(ServerConfiguration cfg) {
    return cfg instanceof MailJndiServerConfiguration || cfg instanceof MailHostServerConfiguration;
}

Try / catch

try {
    mailClient.send(mailMessage);
} catch (FlowableException e) {
    if (e.getMessage().startsWith("Unsupported server configuration")) {
        log.error("Injected config type: {}", mailClient.getServerConfiguration().getClass());
    }
}

Prevention

When it happens

Trigger: Registering a custom ServerConfiguration implementation (or a mock/anonymous object) that is neither MailJndiServerConfiguration nor MailHostServerConfiguration, then triggering mail session creation by sending an email.

Common situations: Custom mail configuration extension code after a Flowable upgrade (pattern matching in switch became exhaustive on known types); passing the wrong configuration object type from plugin code; unit tests stubbing ServerConfiguration with a generic fake.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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