flowable/flowable-engine · critical · ActivitiException

couldn't lookup datasource from ${dataSourceJndiName}: ${e.g

Error message

couldn't lookup datasource from ${dataSourceJndiName}: ${e.getMessage()}

What it means

When no explicit DataSource is configured, the engine can look one up via JNDI using dataSourceJndiName. If InitialContext().lookup fails (name not bound, wrong name, no container JNDI), the engine wraps the failure in this ActivitiException preserving the original message.

Source

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

        initService(managementService);
        initService(dynamicBpmnService);
    }

    protected void initService(Object service) {
        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) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Verify the JNDI name matches the bound resource exactly, including prefix (e.g. java:comp/env/jdbc/ActivitiDS or java:/jdbc/ActivitiDS)
2. Define the DataSource resource in the server (context.xml / *-ds.xml / server resources) so the name exists
3. Alternatively set dataSource directly (or jdbcUrl/jdbcDriver/jdbcUsername) instead of relying on JNDI
4. Check the nested e.getMessage() — NamingException details indicate whether the name or the provider is wrong

Example fix

// before
cfg.setDataSourceJndiName("jdbc/ActivitiDS");
// after
cfg.setDataSourceJndiName("java:comp/env/jdbc/ActivitiDS");

try {
  new InitialContext().lookup(dataSourceJndiName);
} catch (NamingException e) {
  throw new IllegalStateException("JNDI name not bound: " + dataSourceJndiName, e);
} // run this check before buildProcessEngine()

try {
  processEngine = cfg.buildProcessEngine();
} catch (ActivitiException e) {
  if (e.getMessage().startsWith("couldn't lookup datasource")) {
    log.error("JNDI lookup failed for {}: {}", cfg.getDataSourceJndiName(), e.getMessage());
    throw new DataSourceConfigurationException(e);
  } else throw e;
}

When it happens

Trigger: Setting dataSourceJndiName to a JNDI path that is not bound in the naming context (typo, missing resource definition in app server), or running outside an app server where InitialContext has no JNDI provider configured.

Common situations: Deploying the same war to Tomcat (no default JNDI DataSource) after it worked on WildFly; datasource removed/renamed in server config (e.g. jetty/env or context.xml); the JNDI name missing the required java:comp/env or java:/ prefix.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

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