flowable/flowable-engine · critical · IllegalStateException

BPMN engine has not been initialized

Error message

BPMN engine has not been initialized

What it means

This bean in ProcessEngineServicesAutoConfiguration.AlreadyInitializedAppEngineConfiguration only exposes the existing ProcessEngine when the AppEngine has already initialized it. If ProcessEngines.isInitialized() is false at bean creation time, the BPMN (Process) engine was never built, so Flowable throws IllegalStateException instead of returning a null/broken engine. It is a guard for configurations where the process engine should have been created as a side effect of the AppEngine.

Source

Thrown at modules/flowable-spring-boot/flowable-spring-boot-starters/flowable-spring-boot-autoconfigure/src/main/java/org/flowable/spring/boot/ProcessEngineServicesAutoConfiguration.java:75

    /**
     * If an app engine is present that means that the ProcessEngine was created as part of the app engine.
     * Therefore extract it from the ProcessEngines.
     */
    @Configuration(proxyBeanMethods = false)
    @ConditionalOnMissingBean(type = {
        "org.flowable.engine.ProcessEngine"
    })
    @ConditionalOnBean(type = {
        "org.flowable.app.engine.AppEngine"
    })
    static class AlreadyInitializedAppEngineConfiguration {

        @Bean
        public ProcessEngine processEngine(@SuppressWarnings("unused") @Autowired AppEngine appEngine) {
            // The app engine needs to be injected, as otherwise it won't be initialized, which means that the ProcessEngine is not initialized yet
            if (!ProcessEngines.isInitialized()) {
                throw new IllegalStateException("BPMN engine has not been initialized");
            }
            return ProcessEngines.getDefaultProcessEngine();
        }
    }

    /**
     * If there is no app engine configuration, then trigger a creation of the process engine.
     */
    @Configuration(proxyBeanMethods = false)
    @ConditionalOnMissingBean(type = {
        "org.flowable.engine.ProcessEngine",
        "org.flowable.app.engine.AppEngine",
    })
    static class StandaloneEngineConfiguration extends BaseEngineConfigurationWithConfigurers<SpringProcessEngineConfiguration> {
        
        @Bean
        public ProcessEngineFactoryBean processEngine(SpringProcessEngineConfiguration configuration) throws Exception {
            ProcessEngineFactoryBean processEngineFactoryBean = new ProcessEngineFactoryBean();

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the standard ProcessEngineAutoConfiguration/ProcessEngineFactoryBean is active (do not exclude it) so ProcessEngines gets initialized
2. Verify AppEngine configuration actually includes a process engine (appEngine has ProcessEngineConfiguration on classpath)
3. Check earlier startup logs for a swallowed engine-initialization failure (datasource, schema)
4. Add flowable-spring-boot-starter-process (not just app engine starter) if BPMN is intended

Example fix

// before (pom.xml) - only app engine
<dependency>flowable-spring-boot-starter-app</dependency>
// after
<dependency>flowable-spring-boot-starter-process</dependency>

if (!ProcessEngines.isInitialized()) {
    throw new IllegalStateException("ProcessEngine must be initialized before dependent beans are created");
}

try {
    ProcessEngine engine = ProcessEngines.getDefaultProcessEngine();
} catch (IllegalStateException e) {
    logger.error("BPMN engine not initialized: check ProcessEngineAutoConfiguration and engine starter dependencies", e);
    throw e;
}

When it happens

Trigger: Spring context with this auto-configuration active where the AppEngine bean is created but does not (or fails to) initialize a ProcessEngine before the processEngine @Bean method runs; typically a missing/misconfigured app engine configuration or engine creation failure swallowed earlier.

Common situations: Custom Flowable auto-configuration setups where ProcessEngineAutoConfiguration is excluded; AppEngine built without process engine configuration; classpath missing process engine modules so app engine skips BPMN initialization; earlier engine init failure.

Related errors

• CMMN engine has not been initialized
• Form engine is not initialized
• Error while building ibatis SqlSessionFactory:
• There is no engine configuration for scope ${engineScopeType
• Cannot read default EL properties

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