{"record":{"id":"e9f062fa58e5e682","repo":"flowable/flowable-engine","slug":"transactionmanager-is-required-property-for-jtapro","errorCode":null,"errorMessage":"transactionManager is required property for JtaProcessEngineConfiguration, use org.flowable.engine.impl.cfg.StandaloneProcessEngineConfiguration otherwise","messagePattern":"transactionManager is required property for JtaProcessEngineConfiguration, use org\\.flowable\\.engine\\.impl\\.cfg\\.StandaloneProcessEngineConfiguration otherwise","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/cfg/JtaProcessEngineConfiguration.java","lineNumber":36,"sourceCode":"import org.flowable.common.engine.impl.cfg.jta.JtaTransactionContextFactory;\nimport org.flowable.common.engine.impl.interceptor.CommandInterceptor;\nimport org.flowable.common.engine.impl.interceptor.JtaTransactionInterceptor;\n\n/**\n * @author Tom Baeyens\n */\npublic class JtaProcessEngineConfiguration extends ProcessEngineConfigurationImpl {\n\n    protected TransactionManager transactionManager;\n\n    public JtaProcessEngineConfiguration() {\n        this.transactionsExternallyManaged = true;\n    }\n\n    @Override\n    public CommandInterceptor createTransactionInterceptor() {\n        if (transactionManager == null) {\n            throw new FlowableException(\"transactionManager is required property for JtaProcessEngineConfiguration, use \" + StandaloneProcessEngineConfiguration.class.getName() + \" otherwise\");\n        }\n\n        return new JtaTransactionInterceptor(transactionManager);\n    }\n\n    @Override\n    public void initTransactionContextFactory() {\n        if (transactionContextFactory == null) {\n            transactionContextFactory = new JtaTransactionContextFactory(transactionManager);\n        }\n    }\n\n    public TransactionManager getTransactionManager() {\n        return transactionManager;\n    }\n\n    public void setTransactionManager(TransactionManager transactionManager) {\n        this.transactionManager = transactionManager;","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/cfg/JtaProcessEngineConfiguration.java#L18-L54","documentation":"JtaProcessEngineConfiguration requires a JTA TransactionManager; its createTransactionInterceptor override throws this FlowableException at engine bootstrap when transactionManager was never set. The message points you to StandaloneProcessEngineConfiguration as the alternative if you do not run inside a JTA environment. The failure happens while building the command-interceptor chain, i.e. before the process engine becomes usable.","triggerScenarios":"Calling buildProcessEngine() on a JtaProcessEngineConfiguration without calling setTransactionManager(...); creating the config from a flowable.cfg.xml / properties file where the transactionManager property is missing; bootstrapping in a non-JTA environment with the wrong configuration class.","commonSituations":"Migrating from StandaloneProcessEngineConfiguration to JtaProcessEngineConfiguration (e.g. deploying inside WildFly/WebSphere/WebLogic) and forgetting to wire the app server's JTA TransactionManager; misconfigured Java EE datasource setup; copying a standalone flowable.cfg.xml into a JTA environment.","solutions":["Set the JTA transactionManager before buildProcessEngine(), e.g. configuration.setTransactionManager((TransactionManager) new InitialContext().lookup(\"java:/TransactionManager\")) for JNDI-provided JTA","If you do not need JTA, switch to org.flowable.engine.impl.cfg.StandaloneProcessEngineConfiguration so transaction handling matches your environment","In Spring setups, use SpringProcessEngineConfiguration with the Spring PlatformTransactionManager instead of manual JTA wiring"],"exampleFix":"// before\nProcessEngineConfiguration cfg = new JtaProcessEngineConfiguration()\n    .setDataSource(dataSource);\nProcessEngine engine = cfg.buildProcessEngine(); // throws\n\n// after\nTransactionManager tm = (TransactionManager) new InitialContext().lookup(\"java:/TransactionManager\");\nJtaProcessEngineConfiguration cfg = new JtaProcessEngineConfiguration();\ncfg.setDataSource(dataSource);\ncfg.setTransactionManager(tm);\nProcessEngine engine = cfg.buildProcessEngine();","handlingStrategy":"validation","validationCode":"// before buildProcessEngine()\nif (cfg instanceof JtaProcessEngineConfiguration\n    && ((JtaProcessEngineConfiguration) cfg).getTransactionManager() == null) {\n  throw new IllegalStateException(\n    \"JtaProcessEngineConfiguration requires a transactionManager; \"\n    + \"or use StandaloneProcessEngineConfiguration\");\n}","typeGuard":"boolean isJtaConfigReady(ProcessEngineConfiguration cfg) {\n  return !(cfg instanceof JtaProcessEngineConfiguration)\n      || ((JtaProcessEngineConfiguration) cfg).getTransactionManager() != null;\n}","tryCatchPattern":"try {\n  return processEngineConfiguration.buildProcessEngine();\n} catch (FlowableException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"transactionManager is required\")) {\n    throw new IllegalStateException(\n      \"Wire a JTA TransactionManager into the configuration, or switch to \"\n      + \"StandaloneProcessEngineConfiguration\", e);\n  }\n  throw e;\n}","preventionTips":["Match the configuration class to your environment: JTA in app servers, Standalone for plain JVM/Spring Boot","Look up and set the JTA TransactionManager (JNDI) before calling buildProcessEngine()","In Spring, prefer SpringProcessEngineConfiguration with the platform transaction manager","Validate flowable.cfg.xml / properties after environment migrations"],"tags":["flowable","configuration","jta","transaction","bootstrap"],"backgroundTag":"missing-required-config-field","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}