Activiti/Activiti · critical · ActivitiException

transactionManager is required property for…

Error message

transactionManager is required property for JtaProcessEngineConfiguration, use  otherwise

What it means

JtaProcessEngineConfiguration expects an external JTA transaction manager to be injected. createTransactionInterceptor runs during engine bootstrap; if the transactionManager property is null the configuration cannot build the interceptor and throws, suggesting StandaloneProcessEngineConfiguration for setups without a JTA container.

Solutions

Set the JTA transaction manager before building: cfg.setTransactionManager(transactionManager) (obtained via JNDI lookup of java:/TransactionManager or injected by your container).
If you don't need JTA, switch to StandaloneProcessEngineConfiguration (or SpringProcessEngineConfiguration with Spring transaction integration) as the message suggests.
Ensure the transactionManager field isn't being overwritten/reset by a subclass or Spring property binding after configuration.

Example fix

// before
JtaProcessEngineConfiguration cfg = new JtaProcessEngineConfiguration();
cfg.setDataSource(ds);
ProcessEngine engine = cfg.buildProcessEngine(); // throws
// after
JtaProcessEngineConfiguration cfg = new JtaProcessEngineConfiguration();
cfg.setDataSource(ds);
cfg.setTransactionManager((TransactionManager) new InitialContext().lookup("java:/TransactionManager"));
ProcessEngine engine = cfg.buildProcessEngine();

Defensive patterns

Strategy: validation

Validate before calling

if (cfg instanceof JtaProcessEngineConfiguration
    && ((JtaProcessEngineConfiguration) cfg).getTransactionManager() == null) {
    throw new IllegalStateException("JtaProcessEngineConfiguration requires setTransactionManager(...)");
}

Try / catch

try {
    engine = cfg.buildProcessEngine();
} catch (ActivitiException e) {
    if (e.getMessage().startsWith("transactionManager is required")) {
        throw new IllegalStateException("Configure a JTA TransactionManager or switch to StandaloneProcessEngineConfiguration", e);
    }
    throw e;
}

Prevention

Assert transactionManager presence in a configuration unit test before deploying
Use StandaloneProcessEngineConfiguration unless you truly run inside a JTA container
Centralize engine configuration in one factory class so JTA wiring can't be forgotten

When it happens

Trigger: Building a process engine with JtaProcessEngineConfiguration (or the spring-boot/jta variants) and calling buildProcessEngine() without having called setTransactionManager(TransactionManager).

Common situations: Deploying inside an app server (WildFly, WebSphere) but forgetting to look up/inject the UserTransaction/TransactionManager; running in a plain JVM/standalone test where a JTA config was copied from an app-server project; switching from Spring-managed local transactions to JTA without rewiring 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 Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/ef98eaf6290a1ba0. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/cfg/JtaProcessEngineConfiguration.java:38

import org.activiti.engine.impl.cfg.jta.JtaTransactionContextFactory;
import org.activiti.engine.impl.interceptor.CommandInterceptor;
import org.activiti.engine.impl.interceptor.JtaTransactionInterceptor;

/**

 */
public class JtaProcessEngineConfiguration extends ProcessEngineConfigurationImpl {

    protected TransactionManager transactionManager;

    public JtaProcessEngineConfiguration() {
        this.transactionsExternallyManaged = true;
    }

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

        return new JtaTransactionInterceptor(transactionManager);
    }

    @Override
    public void initTransactionContextFactory() {
        if (transactionContextFactory == null) {
            transactionContextFactory = new JtaTransactionContextFactory(transactionManager);
        }
    }

    public TransactionManager getTransactionManager() {
        return transactionManager;

View on GitHub (pinned to 56435b1a97)