{"record":{"id":"b32d89620814af2e","repo":"flowable/flowable-engine","slug":"the-mail-client-provider-is-not-an-instance-of-def","errorCode":null,"errorMessage":"The mail client provider is not an instance of DefaultMailClientProvider. Use setMailClientProvider instead.","messagePattern":"The mail client provider is not an instance of DefaultMailClientProvider\\. Use setMailClientProvider instead\\.","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/CmmnEngineConfiguration.java","lineNumber":4158,"sourceCode":"    }\n\n    /**\n     * @deprecated use {@link #getMailClientProvider()} and {@link MailClientProvider#getMailClient(String)} with tenantId {@code null} instead\n     */\n    @Deprecated\n    public FlowableMailClient getDefaultMailClient() {\n        return mailClientProvider.getMailClient(null);\n    }\n\n    /**\n     * @deprecated use {@link #setMailClientProvider(MailClientProvider)} instead\n     */\n    @Deprecated\n    public CmmnEngineConfiguration setDefaultMailClient(FlowableMailClient defaultMailClient) {\n        if (mailClientProvider instanceof DefaultMailClientProvider defaultProvider) {\n            defaultProvider.setDefaultMailClient(defaultMailClient);\n        } else {\n            throw new FlowableException(\"The mail client provider is not an instance of DefaultMailClientProvider. \"\n                    + \"Use setMailClientProvider instead.\");\n        }\n        return this;\n    }\n\n    public MailServerInfo getDefaultMailServer() {\n        return getOrCreateDefaultMaiLServer();\n    }\n\n    public CmmnEngineConfiguration setDefaultMailServer(MailServerInfo defaultMailServer) {\n        this.defaultMailServer = defaultMailServer;\n        return this;\n    }\n\n    protected MailServerInfo getOrCreateDefaultMaiLServer() {\n        if (defaultMailServer == null) {\n            defaultMailServer = new MailServerInfo();\n            defaultMailServer.setMailServerHost(\"localhost\");","sourceCodeStart":4140,"sourceCodeEnd":4176,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/CmmnEngineConfiguration.java#L4140-L4176","documentation":"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.","triggerScenarios":"Calling setDefaultMailClient(client) after (or while) having configured a custom MailClientProvider via setMailClientProvider(new MyMailClientProvider()).","commonSituations":"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.","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"],"exampleFix":"// before\ncfg.setMailClientProvider(new CustomMailClientProvider());\ncfg.setDefaultMailClient(myClient); // throws\n\n// after\nDefaultMailClientProvider provider = new DefaultMailClientProvider();\nprovider.setDefaultMailClient(myClient);\ncfg.setMailClientProvider(provider);","handlingStrategy":"type-guard","validationCode":"if (!(cmmnEngineConfiguration.getMailClientProvider() instanceof DefaultMailClientProvider)) {\n    // configure via setMailClientProvider instead of setDefaultMailClient\n}","typeGuard":"boolean canUseLegacyDefaultClient(MailClientProvider p) {\n    return p instanceof DefaultMailClientProvider;\n}","tryCatchPattern":"try {\n    cfg.setDefaultMailClient(client);\n} catch (FlowableException e) {\n    if (e.getMessage().contains(\"not an instance of DefaultMailClientProvider\")) {\n        DefaultMailClientProvider p = new DefaultMailClientProvider();\n        p.setDefaultMailClient(client);\n        cfg.setMailClientProvider(p);\n    } else { throw e; }\n}","preventionTips":["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"],"tags":["cmmn","mail","deprecated","configuration"],"backgroundTag":"deprecated-api-usage","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"}