flowable/flowable-engine · error · FlowableException

SpringProcessEngineConfigurator accepts only…

Error message

SpringProcessEngineConfigurator accepts only SpringProcessEngineConfiguration.

What it means

SpringProcessEngineConfigurator.configure checks that the engine configuration it holds is a SpringProcessEngineConfiguration before applying Spring-specific wiring. If the stored processEngineConfiguration is a different ProcessEngineConfiguration subtype, the configurator cannot proceed and throws FlowableException including the offending class name.

Solutions

Ensure the configurator is configured with a SpringProcessEngineConfiguration instance
Remove SpringProcessEngineConfigurator from standalone (non-Spring) engine configurations
Set the configuration explicitly: new SpringProcessEngineConfigurator(new SpringProcessEngineConfiguration())
Audit configurator registration order/types if subclassing

Example fix

// before
new SpringProcessEngineConfigurator(ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration());
// after
new SpringProcessEngineConfigurator(new SpringProcessEngineConfiguration());

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(configurator.getProcessEngineConfiguration() instanceof SpringProcessEngineConfiguration)) {
    throw new IllegalArgumentException("Provide a SpringProcessEngineConfiguration to SpringProcessEngineConfigurator");
}

Type guard

boolean isSpringCfg(AbstractEngineConfiguration c) { return c instanceof SpringProcessEngineConfiguration; }

Try / catch

try { configurator.configure(engineConfiguration); } catch (FlowableException e) { /* inspect e.getMessage() for the offending class name and fix the configurator wiring */ }

Prevention

Only register SpringProcessEngineConfigurator with Spring engine setups
Pass a SpringProcessEngineConfiguration via the constructor/setter
Don't share configurator instances between standalone and Spring engines
Unit-test engine configuration assembly

When it happens

Trigger: A configurator whose processEngineConfiguration field was set (via constructor or setter) to a non-Spring ProcessEngineConfiguration is registered, then configure(AbstractEngineConfiguration) is called during engine build.

Common situations: Using SpringProcessEngineConfigurator in a non-Spring engine setup; custom configurator subclass passing a plain ProcessEngineConfiguration; mixing configurators between standalone and Spring engine builds.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

Thrown at modules/flowable-spring-configurator/src/main/java/org/flowable/engine/spring/configurator/SpringProcessEngineConfigurator.java:34

import org.flowable.common.engine.impl.AbstractEngineConfiguration;
import org.flowable.common.spring.SpringEngineConfiguration;
import org.flowable.engine.configurator.ProcessEngineConfigurator;
import org.flowable.spring.SpringProcessEngineConfiguration;

/**
 * @author Tijs Rademakers
 * @author Joram Barrez
 */
public class SpringProcessEngineConfigurator extends ProcessEngineConfigurator {

    @Override
    public void configure(AbstractEngineConfiguration engineConfiguration) {
        if (processEngineConfiguration == null) {
            processEngineConfiguration = new SpringProcessEngineConfiguration();
        }

        if (!(processEngineConfiguration instanceof SpringProcessEngineConfiguration)) {
            throw new FlowableException("SpringProcessEngineConfigurator accepts only SpringProcessEngineConfiguration. " + processEngineConfiguration.getClass().getName());
        }

        initialiseCommonProperties(engineConfiguration, processEngineConfiguration);

        SpringEngineConfiguration springEngineConfiguration = (SpringEngineConfiguration) engineConfiguration;
        SpringProcessEngineConfiguration springProcessEngineConfiguration = (SpringProcessEngineConfiguration) processEngineConfiguration;
        springProcessEngineConfiguration.setTransactionManager(springEngineConfiguration.getTransactionManager());
        if (springProcessEngineConfiguration.getBeans() == null) {
            springProcessEngineConfiguration.setBeans(springProcessEngineConfiguration.getBeans());
        }

        initEngine();

        initServiceConfigurations(engineConfiguration, processEngineConfiguration);
    }

    @Override
    public SpringProcessEngineConfiguration getProcessEngineConfiguration() {

View on GitHub (pinned to d6d39ce1c6)