Activiti/Activiti · critical · ActivitiException

couldn't lookup datasource from :

Error message

couldn't lookup datasource from :

What it means

When no DataSource object is configured, the engine tries to resolve one via JNDI using the configured dataSourceJndiName. If the InitialContext lookup fails (name not bound, no JNDI provider, wrong type), the NamingException's message is wrapped in this ActivitiException with the original as cause.

Solutions

  1. Verify the JNDI name exactly matches the bound datasource (check server startup logs / admin console for the bound name) and fix setDataSourceJndiName(...).
  2. Ensure you are running inside the environment providing the JNDI context (app server) or add a jndi.properties/InitialContext factory for tests.
  3. Alternatively skip JNDI and configure a direct DataSource or jdbcUrl/jdbcDriver/jdbcUsername/jdbcPassword properties on the configuration.

Example fix

// before
cfg.setDataSourceJndiName("java:jdbc/ActivitiDS"); // name not bound
// after (Tomcat example)
cfg.setDataSourceJndiName("java:comp/env/jdbc/activitiDS");
// or bypass JNDI
cfg.setJdbcUrl("jdbc:h2:tcp://localhost/activiti");
cfg.setJdbcDriver("org.h2.Driver");
Defensive patterns

Strategy: validation

Validate before calling

// verify JNDI binding before configuring the engine
try {
    Object ds = new InitialContext().lookup("java:comp/env/jdbc/activitiDS");
    assert ds instanceof javax.sql.DataSource;
} catch (NamingException e) {
    throw new IllegalStateException("Datasource not bound at expected JNDI name", e);
}

Try / catch

try {
    engine = cfg.buildProcessEngine();
} catch (ActivitiException e) {
    if (e.getMessage().startsWith("couldn't lookup datasource")) {
        // fall back to direct JDBC config
        cfg.setJdbcUrl(...); cfg.setJdbcDriver(...); cfg.setJdbcUsername(...); cfg.setJdbcPassword(...);
        engine = cfg.buildProcessEngine();
    } else throw e;
}

Prevention

When it happens

Trigger: processEngineConfiguration.initDataSource() with dataSource == null and dataSourceJndiName set, when InitialContext().lookup(jndiName) throws — e.g. 'jdbc/activitiDS' not bound, running outside the app server, or NameNotFoundException.

Common situations: Typo in the JNDI name vs the server's resource definition (persistence.xml/web.xml/datasource XML); running unit tests outside the container where no JNDI exists; datasource not deployed/started; missing jee namespace resource-ref mapping in Tomcat.

Understand the failure class

Background: "missing required config value" errors: why libraries refuse to start when a configuration key is empty, unset, or blank — this error's family across 48 libraries.

Related errors

AI-assisted analysis of Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/8c25175589a9c54f. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/cfg/ProcessEngineConfigurationImpl.java:1056

        initService(dynamicBpmnService);
    }

    public void initService(Object service) {
        if (service instanceof ServiceImpl) {
            ((ServiceImpl) service).setCommandExecutor(commandExecutor);
        }
    }

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

    public 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"
                    );
                }

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

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

View on GitHub (pinned to 56435b1a97)