flowable/flowable-engine · error · FlowableException

The mail client provider is not an instance of DefaultMailCl

Error message

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

What it means

Thrown by the deprecated CmmnEngineConfiguration.setDefaultMailClient when the current mailClientProvider is not a DefaultMailClientProvider. The legacy setter can only install a default client into the stock provider; with a custom provider the caller must use setMailClientProvider instead.

Source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/CmmnEngineConfiguration.java:4158

    }

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

    /**
     * @deprecated use {@link #setMailClientProvider(MailClientProvider)} instead
     */
    @Deprecated
    public CmmnEngineConfiguration 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 CmmnEngineConfiguration 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)

Solutions

Stop using the deprecated setter; build a FlowableMailClient and install it via setMailClientProvider(new DefaultMailClientProvider()) with the client pre-registered
Call setDefaultMailClient BEFORE swapping in a custom provider, if you must keep it temporarily
Make the custom provider implement/extend DefaultMailClientProvider so the deprecated setter works
Migrate fully to provider-based configuration and remove @Deprecated setter usage

Example fix

// before
cfg.setMailClientProvider(new CustomMailClientProvider());
cfg.setDefaultMailClient(myClient); // throws

// after
DefaultMailClientProvider provider = new DefaultMailClientProvider();
provider.setDefaultMailClient(myClient);
cfg.setMailClientProvider(provider);

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(cmmnEngineConfiguration.getMailClientProvider() instanceof DefaultMailClientProvider)) {
    // configure via setMailClientProvider instead of setDefaultMailClient
}

Type guard

boolean canUseLegacyDefaultClient(MailClientProvider p) {
    return p instanceof DefaultMailClientProvider;
}

Try / catch

try {
    cfg.setDefaultMailClient(client);
} catch (FlowableException e) {
    if (e.getMessage().contains("not an instance of DefaultMailClientProvider")) {
        DefaultMailClientProvider p = new DefaultMailClientProvider();
        p.setDefaultMailClient(client);
        cfg.setMailClientProvider(p);
    } else { throw e; }
}

Prevention

Migrate off @Deprecated mail setters; use the provider API exclusively
Configure the provider in one place to avoid ordering conflicts
Grep codebase for setDefaultMailClient/setMailClients during provider migrations

When it happens

Trigger: Calling setDefaultMailClient(client) after (or while) having configured a custom MailClientProvider via setMailClientProvider(new MyMailClientProvider()).

Common situations: Mixing old deprecated mail configuration APIs with the newer provider-based API during a migration; a shared configuration bean already replaced the provider; copy-pasted config where the provider line was kept and the deprecated setter added.

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

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