What causes "A datasource is required for initializing the engine " in flowable/flowable-engine?

Set a DataSource on the primary engine configuration before initializing (setDataSource or complete JDBC properties)

flowable/flowable-engine · error · FlowableException

A datasource is required for initializing the engine

Error message

A datasource is required for initializing the engine

What it means

When a dependent engine (e.g. process engine configured from/with another engine) is initialized via AbstractEngineConfigurator, the datasource is copied from the source engine configuration. If the source configuration has no DataSource, initialization cannot proceed and this FlowableException is thrown.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfigurator.java:286

        targetEngineConfiguration.setEventRegistryEventConsumers(engineConfiguration.getEventRegistryEventConsumers());
    }

    protected void initCommandContextFactory(AbstractEngineConfiguration engineConfiguration, AbstractEngineConfiguration targetEngineConfiguration) {
        targetEngineConfiguration.setCommandContextFactory(engineConfiguration.getCommandContextFactory());
    }

    protected void initIdGenerator(AbstractEngineConfiguration engineConfiguration, AbstractEngineConfiguration targetEngineConfiguration) {
        if (targetEngineConfiguration.getIdGenerator() == null) {
            targetEngineConfiguration.setIdGenerator(engineConfiguration.getIdGenerator());
        }
        targetEngineConfiguration.setUsePrefixId(engineConfiguration.isUsePrefixId());
    }

    protected void initDataSource(AbstractEngineConfiguration engineConfiguration, AbstractEngineConfiguration targetEngineConfiguration) {
        if (engineConfiguration.getDataSource() != null) {
            targetEngineConfiguration.setDataSource(engineConfiguration.getDataSource());
        } else {
            throw new FlowableException("A datasource is required for initializing the engine ");
        }
    }

    protected void initDbSqlSessionFactory(AbstractEngineConfiguration engineConfiguration, AbstractEngineConfiguration targetEngineConfiguration) {
        targetEngineConfiguration.setDbSqlSessionFactory(engineConfiguration.getDbSqlSessionFactory());
        targetEngineConfiguration.setSqlSessionFactory(engineConfiguration.getSqlSessionFactory());
        targetEngineConfiguration.defaultInitDbSqlSessionFactoryEntitySettings(getEntityInsertionOrder(), getEntityDeletionOrder());
    }

    protected void initSessionFactories(AbstractEngineConfiguration engineConfiguration, AbstractEngineConfiguration targetEngineConfiguration) {
        targetEngineConfiguration.setSessionFactories(engineConfiguration.getSessionFactories());
    }

    protected void initDbProperties(AbstractEngineConfiguration engineConfiguration, AbstractEngineConfiguration targetEngineConfiguration) {
        targetEngineConfiguration.setDatabaseType(engineConfiguration.getDatabaseType());
        targetEngineConfiguration.setDatabaseCatalog(engineConfiguration.getDatabaseCatalog());
        targetEngineConfiguration.setDatabaseSchema(engineConfiguration.getDatabaseSchema());
        targetEngineConfiguration.setDatabaseSchemaUpdate(engineConfiguration.getDatabaseSchemaUpdate());

View on GitHub (pinned to d6d39ce1c6)

Solutions

Set a DataSource on the primary engine configuration before initializing (setDataSource or complete JDBC properties)
Ensure the primary engine's initDataSource runs successfully (fix JNDI/JDBC configuration errors first)
Check configurator registration so the shared datasource is available to dependent engines

Example fix

// before
ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration().buildProcessEngine(); // no datasource
// after
ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration()
    .setJdbcUrl("jdbc:h2:mem:flowable")
    .setJdbcDriver("org.h2.Driver")
    .setJdbcUsername("sa")
    .buildProcessEngine();

Defensive patterns

Strategy: validation

Validate before calling

if (engineConfig.getDataSource() == null) { throw new IllegalStateException("set a DataSource before initializing engines that share configuration"); }

Try / catch

try { dependentEngine = buildDependentEngine(); } catch (FlowableException e) { if (e.getMessage().startsWith("A datasource is required")) { /* configure datasource on primary engine and retry */ } throw e; }

Prevention

Configure the primary engine's DataSource before dependent engines
In multi-engine setups, verify datasource propagation in startup tests
Avoid standalone configs that bypass datasource initialization when configurators are present

When it happens

Trigger: initDataSource (called from initialiseCommonProperties during dependent-engine setup) when engineConfiguration.getDataSource() == null, i.e. the primary engine configuration was never given a DataSource (or its JNDI/JDBC fallback did not produce one).

Common situations: Multi-engine setups (process + cmmn/dmn/form engines) where the primary engine is configured without a datasource, or configurator ordering/initialization skipped datasource creation.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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