flowable/flowable-engine · error · FlowableException

no org.flowable.engine.ProcessEngine defined in the applicat

Error message

no org.flowable.engine.ProcessEngine defined in the application context

What it means

SpringConfigurationHelper.buildProcessEngine loads a Spring XML application context from the given URL and searches it for a bean of type org.flowable.engine.ProcessEngine. If the context contains no such bean (or the lookup returns null/empty), it throws this FlowableException. It means the Spring configuration file provided to the helper does not actually define a Flowable process engine.

Source

Thrown at modules/flowable-spring/src/main/java/org/flowable/spring/SpringConfigurationHelper.java:39

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.support.GenericXmlApplicationContext;
import org.springframework.core.io.UrlResource;

/**
 * @author Tom Baeyens
 */
public class SpringConfigurationHelper {

    private static final Logger LOGGER = LoggerFactory.getLogger(SpringConfigurationHelper.class);

    public static ProcessEngine buildProcessEngine(URL resource) {
        LOGGER.debug("==== BUILDING SPRING APPLICATION CONTEXT AND PROCESS ENGINE =========================================");

        try (GenericXmlApplicationContext applicationContext = new GenericXmlApplicationContext(new UrlResource(resource))) {
            Map<String, ProcessEngine> beansOfType = applicationContext.getBeansOfType(ProcessEngine.class);
            if ((beansOfType == null) || beansOfType.isEmpty()) {
                throw new FlowableException("no " + ProcessEngine.class.getName() + " defined in the application context " + resource);
            }

            ProcessEngine processEngine = beansOfType.values().iterator().next();

            LOGGER.debug("==== SPRING PROCESS ENGINE CREATED ==================================================================");
            return processEngine;
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Add a SpringProcessEngineConfiguration bean (which exposes a ProcessEngine) to the XML context passed to buildProcessEngine.
  2. Check the URL/resource path — verify it resolves to the intended XML file (log/print resource and inspect it).
  3. If the engine bean lives in another context file, merge or import it into the context being loaded.
  4. If you do not need Spring wiring, use ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration() instead of the Spring helper.

Example fix

// before: XML with no engine bean
<beans>...</beans>

// after: define the engine bean in the context passed to buildProcessEngine
<bean id="processEngineConfiguration" class="org.flowable.spring.SpringProcessEngineConfiguration">
    <property name="dataSource" ref="dataSource"/>
    <property name="transactionManager" ref="transactionManager"/>
    <property name="databaseSchemaUpdate" value="true"/>
</bean>
<bean id="processEngine" class="org.flowable.spring.ProcessEngineFactoryBean">
    <property name="processEngineConfiguration" ref="processEngineConfiguration"/>
</bean>
Defensive patterns

Strategy: validation

Validate before calling

GenericXmlApplicationContext ctx = new GenericXmlApplicationContext(new UrlResource(resource));
boolean ok = !ctx.getBeansOfType(ProcessEngine.class).isEmpty();
if (!ok) throw new IllegalStateException("XML context " + resource + " defines no ProcessEngine bean");

Try / catch

try {
    ProcessEngine engine = SpringConfigurationHelper.buildProcessEngine(url);
} catch (FlowableException e) {
    // log the resource URL and fail startup with a clear config message
}

Prevention

When it happens

Trigger: Calling SpringConfigurationHelper.buildProcessEngine(url) with an XML resource that has no <bean> of type ProcessEngine / SpringProcessEngineConfiguration, or where the engine bean is defined in a different (imported, not imported) context.

Common situations: Pointing the helper at the wrong XML file or one missing the flowable engine configuration; engine bean defined in a parent context not loaded by this URL; classpath resource resolution loading an empty/stale file; migration where the bean id/type was renamed.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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