flowable/flowable-engine · error · FlowableException

DataSource or JDBC properties have to be specified in a proc

Error message

DataSource or JDBC properties have to be specified in a process engine configuration

What it means

When neither a DataSource nor a JNDI name is configured, the engine falls back to building a datasource from JDBC properties. If jdbcUrl is set but jdbcDriver or jdbcUsername is missing, configuration cannot proceed and this FlowableException is thrown.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfiguration.java:431

    protected void initEngineConfigurations() {
        addEngineConfiguration(getEngineCfgKey(), getEngineScopeType(), this);
    }

    // DataSource
    // ///////////////////////////////////////////////////////////////

    protected void initDataSource() {
        if (dataSource == null) {
            if (dataSourceJndiName != null) {
                try {
                    dataSource = (DataSource) new InitialContext().lookup(dataSourceJndiName);
                } catch (Exception e) {
                    throw new FlowableException("couldn't lookup datasource from " + dataSourceJndiName + ": " + e.getMessage(), e);
                }

            } else if (jdbcUrl != null) {
                if ((jdbcDriver == null) || (jdbcUsername == null)) {
                    throw new FlowableException("DataSource or JDBC properties have to be specified in a process engine configuration");
                }

                logger.debug("initializing datasource to db: {}", jdbcUrl);

                if (logger.isInfoEnabled()) {
                    logger.info("Configuring Datasource with following properties (omitted password for security)");
                    logger.info("datasource driver : {}", jdbcDriver);
                    logger.info("datasource url : {}", jdbcUrl);
                    logger.info("datasource user name : {}", jdbcUsername);
                }

                PooledDataSource pooledDataSource = new PooledDataSource(this.getClass().getClassLoader(), jdbcDriver, jdbcUrl, jdbcUsername, jdbcPassword);

                if (jdbcMaxActiveConnections > 0) {
                    pooledDataSource.setPoolMaximumActiveConnections(jdbcMaxActiveConnections);
                }
                if (jdbcMaxIdleConnections > 0) {
                    pooledDataSource.setPoolMaximumIdleConnections(jdbcMaxIdleConnections);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set jdbcDriver (fully qualified driver class name) and jdbcUsername (and jdbcPassword) alongside jdbcUrl
2. Or provide a javax.sql.DataSource directly via setDataSource()
3. Or configure dataSourceJndiName if running in an app server

Example fix

// before
config.setJdbcUrl("jdbc:h2:mem:flowable");
// after
config.setJdbcUrl("jdbc:h2:mem:flowable");
config.setJdbcDriver("org.h2.Driver");
config.setJdbcUsername("sa");
config.setJdbcPassword("");

if (config.getDataSource() == null && config.getDataSourceJndiName() == null && config.getJdbcUrl() != null) { requireNonNull(config.getJdbcDriver(), "jdbcDriver required"); requireNonNull(config.getJdbcUsername(), "jdbcUsername required"); }

When it happens

Trigger: AbstractEngineConfiguration.initDataSource() with dataSource == null, dataSourceJndiName == null, jdbcUrl != null, and either jdbcDriver == null or jdbcUsername == null.

Common situations: Incomplete spring/boot config (only url given), missing properties file entries, renaming config keys after upgrade, forgetting to set credentials for the JDBC connection.

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

• couldn't lookup datasource from
• A datasource is required for initializing the engine
• Could not find a dataSource for tenant ${tenantId}
• DataSource or JDBC properties have to be specified in a proc
• no org.flowable.app.engine.AppEngine defined in the applicat

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