flowable/flowable-engine · error · FlowableException

The mail client provider is not an instance of…

Error message

The mail client provider is not an instance of DefaultMailClientProvider. Use setMailClientProvider instead.

What it means

The deprecated setDefaultMailClient(FlowableMailClient) only works when the configured mailClientProvider is (or implements) DefaultMailClientProvider, because it delegates to that provider's setDefaultMailClient. If a custom MailClientProvider was installed, Flowable throws instead of silently bypassing it, and directs you to configure the client via setMailClientProvider.

Solutions

1. Create a DefaultMailClientProvider, set the default client on it, and pass it via setMailClientProvider(...)
2. Call setDefaultMailClient before installing any custom provider (only valid if the default provider is still in place)
3. Remove the custom provider if you don't actually need provider-level control

Example fix

// before
config.setMailClientProvider(customProvider);
config.setDefaultMailClient(new SimpleMailClient());

// after
DefaultMailClientProvider provider = new DefaultMailClientProvider();
provider.setDefaultMailClient(new SimpleMailClient());
config.setMailClientProvider(provider);

if (!(config.getMailClientProvider() instanceof DefaultMailClientProvider)) {
    throw new IllegalStateException("setDefaultMailClient requires DefaultMailClientProvider");
}
config.setDefaultMailClient(client);

boolean canSetDefaultMailClient(ProcessEngineConfiguration c) {
    return c.getMailClientProvider() instanceof DefaultMailClientProvider;
}

When it happens

Trigger: Calling processEngineConfiguration.setDefaultMailClient(client) after having set a custom MailClientProvider via setMailClientProvider(...) that is not a DefaultMailClientProvider.

Common situations: Applications integrating a custom mail provider (e.g. sending via a provider SDK) then upgrading Flowable code that still uses the deprecated setter; migration from the old mail-server properties to the new mail-client API.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• Cannot use startProcessByName in an active command.
• no SMTP host is configured for the default mail server
• no SMTP host is configured for the mail server for tenant
• The mail client provider is not an instance of…
• Usage of deprecated property. Use FlowableProcessProperties

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/ProcessEngineConfiguration.java:276

    }

    /**
     * @deprecated use {@link #getMailClientProvider()} and {@link MailClientProvider#getMailClient(String)} with {@code null} instead
     */
    @Deprecated
    public FlowableMailClient getDefaultMailClient() {
        return mailClientProvider.getMailClient(null);
    }

    /**
     * @deprecated use {@link #setMailClientProvider(MailClientProvider)} instead
     */
    @Deprecated
    public ProcessEngineConfiguration setDefaultMailClient(FlowableMailClient defaultMailClient) {
        if (mailClientProvider instanceof DefaultMailClientProvider defaultProvider) {
            defaultProvider.setDefaultMailClient(defaultMailClient);
        } else {
            throw new FlowableException("The mail client provider is not an instance of DefaultMailClientProvider. "
                    + "Use setMailClientProvider instead.");
        }
        return this;
    }

    public MailServerInfo getDefaultMailServer() {
        return getOrCreateDefaultMaiLServer();
    }

    public ProcessEngineConfiguration setDefaultMailServer(MailServerInfo defaultMailServer) {
        this.defaultMailServer = defaultMailServer;
        return this;
    }

    protected MailServerInfo getOrCreateDefaultMaiLServer() {
        if (defaultMailServer == null) {
            defaultMailServer = new MailServerInfo();
            defaultMailServer.setMailServerHost("localhost");

View on GitHub (pinned to d6d39ce1c6)