flowable/flowable-engine · error · ActivitiException

Unsupported process engine configuration

Error message

Unsupported process engine configuration

What it means

DefaultProcessEngineFactory.buildProcessEngine only knows how to build an Activiti 5 engine from a Flowable 6 StandaloneProcessEngineConfiguration; any other ProcessEngineConfigurationImpl subtype is rejected with this ActivitiException. It is a configuration-type guard in the flowable5-compatibility bridge.

Solutions

1. Use StandaloneProcessEngineConfiguration when constructing the engine for the factory
2. If using Spring, build the engine via the Spring integration path instead of DefaultProcessEngineFactory
3. Extend/copy the factory to support your configuration type (add copyConfigItems handling for your subclass)

Example fix

// before
SpringProcessEngineConfiguration cfg = new SpringProcessEngineConfiguration();
ProcessEngine engine = new DefaultProcessEngineFactory().buildProcessEngine(cfg); // throws
// after
StandaloneProcessEngineConfiguration cfg = new StandaloneProcessEngineConfiguration();
cfg.setJdbcUrl(...);
ProcessEngine engine = new DefaultProcessEngineFactory().buildProcessEngine(cfg);

if (!(config instanceof StandaloneProcessEngineConfiguration)) {
  throw new IllegalArgumentException("DefaultProcessEngineFactory requires StandaloneProcessEngineConfiguration");
}

boolean supported(ProcessEngineConfigurationImpl cfg) {
  return cfg instanceof StandaloneProcessEngineConfiguration;
}

try {
  engine = factory.buildProcessEngine(cfg);
} catch (ActivitiException e) {
  if (e.getMessage().contains("Unsupported process engine configuration")) {
    engine = buildEngineViaSpringPath(cfg);
  } else throw e;
}

When it happens

Trigger: Calling DefaultProcessEngineFactory.buildProcessEngine(config) with a config that is not an instance of StandaloneProcessEngineConfiguration (e.g. SpringProcessEngineConfiguration, custom subclass).

Common situations: Embedding the Activiti 5 compatibility engine inside a Spring Boot app using SpringProcessEngineConfiguration; custom configuration classes built via builder patterns.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• A channel key detection value is required for the channel…
• A datasource is required for initializing the engine
• Builder is missing constructor (can't pass features)
• Can't deploy a v5 deployment with no flowable 5…
• Candidate group is null

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

Appendix: source

Thrown at modules/flowable5-compatibility/src/main/java/org/flowable/compatibility/DefaultProcessEngineFactory.java:47

import org.flowable.common.engine.impl.EngineDeployer;
import org.flowable.common.engine.impl.history.HistoryLevel;
import org.flowable.engine.impl.cfg.ProcessEngineConfigurationImpl;
import org.flowable.engine.impl.cfg.StandaloneProcessEngineConfiguration;
import org.flowable.engine.impl.rules.RulesDeployer;

public class DefaultProcessEngineFactory {

    /**
     * Takes in an Flowable 6 process engine config, gives back an Flowable 5 Process engine.
     */
    public ProcessEngine buildProcessEngine(ProcessEngineConfigurationImpl flowable6Configuration) {
        org.activiti.engine.impl.cfg.ProcessEngineConfigurationImpl flowable5Configuration = null;
        if (flowable6Configuration instanceof StandaloneProcessEngineConfiguration) {
            flowable5Configuration = new org.activiti.engine.impl.cfg.StandaloneProcessEngineConfiguration();
            copyConfigItems(flowable6Configuration, flowable5Configuration);
            return flowable5Configuration.buildProcessEngine();
        } else {
            throw new ActivitiException("Unsupported process engine configuration");
        }
    }

    protected void copyConfigItems(ProcessEngineConfigurationImpl flowable6Configuration, org.activiti.engine.impl.cfg.ProcessEngineConfigurationImpl flowable5Configuration) {
        flowable5Configuration.setFlowable5CompatibilityHandler(flowable6Configuration.getFlowable5CompatibilityHandler());

        copyJdbcConfig(flowable6Configuration, flowable5Configuration);
        copyHistoryConfig(flowable6Configuration, flowable5Configuration);
        copyMailConfig(flowable6Configuration, flowable5Configuration);
        copyDiagramConfig(flowable6Configuration, flowable5Configuration);
        copyAsyncExecutorConfig(flowable6Configuration, flowable5Configuration);
        copyJpaConfig(flowable6Configuration, flowable5Configuration);
        copyBeans(flowable6Configuration, flowable5Configuration);
        copyCaches(flowable6Configuration, flowable5Configuration);
        copyActivityBehaviorFactory(flowable6Configuration, flowable5Configuration);
        copyExpressionManager(flowable6Configuration, flowable5Configuration);
        copyListenerFactory(flowable6Configuration, flowable5Configuration);
        convertParseHandlers(flowable6Configuration, flowable5Configuration);

View on GitHub (pinned to d6d39ce1c6)