flowable/flowable-engine · error · FlowableException

no org.flowable.eventregistry.api.EventRegistryEngine define

Error message

no org.flowable.eventregistry.api.EventRegistryEngine defined in the application context <resource>

What it means

SpringEventConfigurationHelper.buildEventRegistryEngine boots a Spring XML application context from a URL and looks up a bean of type org.flowable.eventregistry.api.EventRegistryEngine. If the context loads but contains no such bean, it throws this FlowableException. It means the XML resource exists but does not define an EventRegistryEngine bean (typically a SpringEventRegistryEngineConfiguration bean producing one).

Source

Thrown at modules/flowable-event-registry-spring/src/main/java/org/flowable/eventregistry/spring/SpringEventConfigurationHelper.java:36

import org.flowable.common.engine.api.FlowableException;
import org.flowable.eventregistry.impl.EventRegistryEngine;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.support.GenericXmlApplicationContext;
import org.springframework.core.io.UrlResource;

public class SpringEventConfigurationHelper {

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

    public static EventRegistryEngine buildEventRegistryEngine(URL resource) {
        LOGGER.debug("==== BUILDING SPRING APPLICATION CONTEXT AND EVENT REGISTRY =========================================");

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

            EventRegistryEngine eventRegistryEngine = beansOfType.values().iterator().next();

            LOGGER.debug("==== SPRING EVENT REGISTRY CREATED ==================================================================");
            return eventRegistryEngine;
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Inspect the XML resource and add an EventRegistryEngine bean definition (e.g. a SpringEventRegistryEngineConfiguration bean).
Verify the resource URL/classpath location actually points to the intended event-registry Spring context file.
Check the bean's class implements org.flowable.eventregistry.api.EventRegistryEngine (not just an engine configuration).
After upgrades, confirm bean naming/type conventions still match the Flowable version in use.

Example fix

<!-- before: context has no event registry engine bean -->
<bean id="processEngineConfiguration" class="org.flowable.spring.SpringProcessEngineConfiguration"/>

<!-- after -->
<bean id="eventRegistryEngineConfiguration" class="org.flowable.eventregistry.spring.SpringEventRegistryEngineConfiguration">
  <property name="dataSource" ref="dataSource"/>
  <property name="transactionManager" ref="transactionManager"/>
</bean>
<bean id="eventRegistryEngine" factory-bean="eventRegistryEngineConfiguration" factory-method="buildEventRegistryEngine"/>

Defensive patterns

Strategy: validation

Validate before calling

// Validate the XML context defines an EventRegistryEngine before building
GenericXmlApplicationContext ctx = new GenericXmlApplicationContext(new UrlResource(resource));
if (ctx.getBeansOfType(EventRegistryEngine.class).isEmpty()) {
    throw new IllegalStateException("Resource lacks EventRegistryEngine bean: " + resource);
}
ctx.close();

Type guard

boolean isEventRegistryEngineBean(Object bean) { return bean instanceof org.flowable.eventregistry.api.EventRegistryEngine; }

Prevention

Keep a dedicated, reviewed Spring XML for the event registry engine.
Assert engine bean presence in an integration test that boots the resource.
Verify resource URLs resolve to the intended files at startup.

When it happens

Trigger: Calling FlowableEventRegistryEngineConfiguration (SpringEventConfigurationHelper).buildEventRegistryEngine(URL) with an XML resource whose context has no EventRegistryEngine bean, or a bean of a different/wrong type, or the engine bean is defined but not of the expected interface.

Common situations: Pointing the resource URL at the wrong XML file; the XML defines a process-engine configuration instead of an event-registry one; missing the <flowable:event-registry-engine> style bean definition; bean type mismatch after a Flowable version upgrade.

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/e4fe335549d7c049. Report an issue: GitHub.