flowable/flowable-engine · critical · ActivitiException

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

If neither dataSource nor dataSourceJndiName is set, the engine falls back to building a pooled datasource from jdbcUrl. That fallback requires jdbcDriver and jdbcUsername to also be set; if either is null, initDataSource throws this ActivitiException because a connection cannot be established.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cfg/ProcessEngineConfigurationImpl.java:730

        if (service instanceof ServiceImpl) {
            ((ServiceImpl) service).setCommandExecutor(commandExecutor);
        }
    }

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

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

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

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

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

                if (jdbcMaxActiveConnections > 0) {
                    pooledDataSource.setPoolMaximumActiveConnections(jdbcMaxActiveConnections);
                }
                if (jdbcMaxIdleConnections > 0) {
                    pooledDataSource.setPoolMaximumIdleConnections(jdbcMaxIdleConnections);
                }
                if (jdbcMaxCheckoutTime > 0) {
                    pooledDataSource.setPoolMaximumCheckoutTime(jdbcMaxCheckoutTime);
                }
                if (jdbcMaxWaitTime > 0) {
                    pooledDataSource.setPoolTimeToWait(jdbcMaxWaitTime);
                }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Set all three: jdbcUrl, jdbcDriver (e.g. org.h2.Driver) and jdbcUsername (jdbcPassword optional) on the configuration
Or provide a ready-made DataSource via setDataSource(...) and skip JDBC properties
Or set dataSourceJndiName to a bound JNDI resource
Review your activiti.cfg.xml / Spring bean for the missing jdbcDriver or jdbcUsername property

Example fix

// before
cfg.setJdbcUrl("jdbc:h2:mem:activiti");
cfg.buildProcessEngine(); // throws
// after
cfg.setJdbcUrl("jdbc:h2:mem:activiti");
cfg.setJdbcDriver("org.h2.Driver");
cfg.setJdbcUsername("sa");
cfg.setJdbcPassword("");
cfg.buildProcessEngine();

Defensive patterns

Strategy: validation

Validate before calling

if (cfg.getDataSource() == null && cfg.getDataSourceJndiName() == null) {
  if (cfg.getJdbcUrl() == null || cfg.getJdbcDriver() == null || cfg.getJdbcUsername() == null) {
    throw new IllegalStateException("Set jdbcUrl + jdbcDriver + jdbcUsername, a DataSource, or a JNDI name");
  }
}

Try / catch

try {
  processEngine = cfg.buildProcessEngine();
} catch (ActivitiException e) {
  if (e.getMessage().contains("DataSource or JDBC properties have to be specified")) {
    throw new ConfigurationException("Incomplete JDBC config: driver/username missing", e);
  } else throw e;
}

Prevention

Set jdbcUrl, jdbcDriver and jdbcUsername together whenever using JDBC properties
Or pass a fully constructed DataSource via setDataSource
Keep activiti.cfg.xml properties in sync with documentation/examples
Add a config self-check before buildProcessEngine

When it happens

Trigger: Configuration with jdbcUrl set but jdbcDriver or jdbcUsername left null when buildProcessEngine initializes the datasource — e.g. only setJdbcUrl called, or XML config missing the driver/username properties.

Common situations: Partial JDBC configuration copied from examples; switching from a container-managed datasource to JDBC properties and forgetting username; H2 in-memory setups that omit the driver class.

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