flowable/flowable-engine · error · FlowableException

transactionManager is required property for SpringProcessEng

Error message

transactionManager is required property for SpringProcessEngineConfiguration, use org.flowable.engine.impl.cfg.StandaloneProcessEngineConfiguration otherwise

What it means

SpringProcessEngineConfiguration is the Flowable engine configuration for Spring-managed transactions; it delegates all transaction handling to a Spring PlatformTransactionManager. createTransactionInterceptor validates this: if no transactionManager property was set, the configuration is unusable and a FlowableException is thrown, telling you to use StandaloneProcessEngineConfiguration instead if you don't want Spring transactions.

Source

Thrown at modules/flowable-spring/src/main/java/org/flowable/spring/SpringProcessEngineConfiguration.java:108

    protected EngineConfigurator createDefaultEventRegistryEngineConfigurator() {
        return new SpringEventRegistryConfigurator();
    }

    public void setTransactionSynchronizationAdapterOrder(Integer transactionSynchronizationAdapterOrder) {
        this.transactionSynchronizationAdapterOrder = transactionSynchronizationAdapterOrder;
    }

    @Override
    public void initDefaultCommandConfig() {
        if (defaultCommandConfig == null) {
            defaultCommandConfig = new CommandConfig().setContextReusePossible(true);
        }
    }

    @Override
    public CommandInterceptor createTransactionInterceptor() {
        if (transactionManager == null) {
            throw new FlowableException("transactionManager is required property for SpringProcessEngineConfiguration, use " + StandaloneProcessEngineConfiguration.class.getName() + " otherwise");
        }

        return new SpringTransactionInterceptor(transactionManager);
    }

    @Override
    public void initTransactionContextFactory() {
        if (transactionContextFactory == null && transactionManager != null) {
            transactionContextFactory = new SpringTransactionContextFactory(transactionManager, transactionSynchronizationAdapterOrder);
        }
    }

    @Override
    public void initJpa() {
        super.initJpa();
        if (jpaEntityManagerFactory != null) {
            sessionFactories.put(EntityManagerSession.class, new SpringEntityManagerSessionFactory(jpaEntityManagerFactory, jpaHandleTransaction, jpaCloseEntityManager));
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Set the transactionManager property on the SpringProcessEngineConfiguration to a Spring PlatformTransactionManager bean (e.g. DataSourceTransactionManager or JtaTransactionManager).
If you truly run without Spring transactions, switch the configuration class to StandaloneProcessEngineConfiguration as the message suggests.
In Spring Boot, use the SpringProcessEngineConfiguration provided by flowable-spring-boot-starter auto-configuration rather than constructing your own.

Example fix

// before
SpringProcessEngineConfiguration cfg = new SpringProcessEngineConfiguration();
cfg.setDataSource(dataSource);

// after
cfg.setTransactionManager(new DataSourceTransactionManager(dataSource));
// or, if not using Spring transactions:
// ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration()...

Defensive patterns

Strategy: validation

Validate before calling

if (cfg instanceof SpringProcessEngineConfiguration && ((SpringProcessEngineConfiguration) cfg).getTransactionManager() == null) {
    throw new IllegalStateException("Set transactionManager before building the engine");
}

Prevention

Always wire <property name="transactionManager" ref="transactionManager"/> when using SpringProcessEngineConfiguration
Define a PlatformTransactionManager bean alongside the DataSource
Use StandaloneProcessEngineConfiguration when Spring transaction management is not wanted

When it happens

Trigger: Building/obtaining a process engine from a SpringProcessEngineConfiguration where the transactionManager property was never set (missing <property name="transactionManager"> in XML, or omitted in Java config), which surfaces when the engine initializes its command interceptor chain.

Common situations: Hand-written Spring XML missing the transactionManager wiring; copying a standalone engine config class into a Spring app; DataSource present but PlatformTransactionManager bean never defined; Spring Boot auto-config overridden by a custom configuration bean that forgot the property.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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