flowable/flowable-engine · critical · FlowableException

couldn't initialize event registry engine from spring config

Error message

couldn't initialize event registry engine from spring configuration resource 

What it means

Flowable throws this when building an Event Registry engine from a Spring configuration XML resource fails. initEventRegistryEngineFromSpringResource parses the resource into an EventRegistryEngineConfiguration; any exception (parse error, bean wiring failure, DB failure during buildEventRegistryEngine) is wrapped in a FlowableException with the resource URL and root cause message appended. It is a fatal engine bootstrap failure.

Source

Thrown at modules/flowable-event-registry/src/main/java/org/flowable/eventregistry/impl/EventRegistryEngines.java:106

            setInitialized(true);
        } else {
            LOGGER.info("Event registry engines already initialized");
        }
    }

    protected static void initEventRegistryEngineFromSpringResource(URL resource) {
        try {
            Class<?> springConfigurationHelperClass = ReflectUtil.loadClass("org.flowable.eventregistry.impl.spring.SpringEventRegistryConfigurationHelper");
            Method method = springConfigurationHelperClass.getDeclaredMethod("buildEventRegistryEngine", new Class<?>[] { URL.class });
            EventRegistryEngine eventRegistryEngine = (EventRegistryEngine) method.invoke(null, new Object[] { resource });

            String eventRegistryEngineName = eventRegistryEngine.getName();
            EngineInfo eventRegistryEngineInfo = new EngineInfo(eventRegistryEngineName, resource.toString(), null);
            eventRegistryEngineInfosByName.put(eventRegistryEngineName, eventRegistryEngineInfo);
            eventRegistryEngineInfosByResourceUrl.put(resource.toString(), eventRegistryEngineInfo);

        } catch (Exception e) {
            throw new FlowableException("couldn't initialize event registry engine from spring configuration resource " + resource + ": " + e.getMessage(), e);
        }
    }

    /**
     * Registers the given event registry engine. No {@link EngineInfo} will be available for this event registry engine. An engine that is registered will be closed when the {@link EventRegistryEngines#destroy()} is called.
     */
    public static void registerEventRegistryEngine(EventRegistryEngine eventRegistryEngine) {
        eventRegistryEngines.put(eventRegistryEngine.getName(), eventRegistryEngine);
    }

    /**
     * Unregisters the given event registry engine.
     */
    public static void unregister(EventRegistryEngine eventRegistryEngine) {
        eventRegistryEngines.remove(eventRegistryEngine.getName());
    }

    private static EngineInfo initEventRegistryEngineFromResource(URL resourceUrl) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Read the chained cause (e.getMessage() part) to find the real failure: XML parse error, missing bean, or DB connection failure
2. Validate the Spring XML resource parses standalone (e.g. load it with ClassPathXmlApplicationContext in a test)
3. Verify the datasource and database are reachable before engine init
4. Ensure the flowable-event-registry-spring module and all bean classes referenced in the XML are on the classpath

Example fix

// before
<bean id="eventRegistryEngineConfiguration" class="org.flowable.eventregistry.spring.config.EventRegistryEngineConfiguration">
  <property name="dataSource" ref="dtaSource" /> <!-- typo -->
</bean>
// after
<bean id="eventRegistryEngineConfiguration" class="org.flowable.eventregistry.spring.config.EventRegistryEngineConfiguration">
  <property name="dataSource" ref="dataSource" />
</bean>

// before init: sanity-check the Spring resource
try (InputStream is = getClass().getResourceAsStream("/flowable-eventregistry.cfg.xml")) {
    if (is == null) throw new IllegalStateException("event registry spring config missing");
    new javax.xml.parsers.DocumentBuilderFactory().newInstance().newDocumentBuilder().parse(is); // well-formed?
}

boolean isUsableUrl(URL u) { return u != null && ("file".equals(u.getProtocol()) ? new java.io.File(u.getPath()).canRead() : true); }

try {
    EventRegistryEngines.init();
} catch (FlowableException e) {
    LOGGER.error("Event registry engine init failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage(), e);
    throw new IllegalStateException("abort startup: event registry not initialized", e);
}

When it happens

Trigger: Calling EventRegistryEngines.init() (directly or via Spring engine auto-init) with flowable.eventregistry.cfg.xml-style Spring resources where the XML is malformed, references missing beans/classes, or the engine build inside the config fails (e.g. database unreachable, invalid datasource).

Common situations: Typo or wrong schema in the Spring config XML; datasource bean misconfigured or DB down at startup; missing flowable-event-registry-spring jar so a referenced class is absent; resource URL resolves to a stale/empty file.

Related errors

• couldn't initialize process engine from spring configuration
• no org.flowable.app.engine.AppEngine defined in the applicat
• transactionManager is required property for SpringAppEngineC
• couldn't initialize app engine from spring configuration res
• transactionManager is required property for SpringCmmnEngine

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