What causes "couldn't lookup datasource from " in flowable/flowable-engine?

Verify the exact JNDI name exists in the container and matches dataSourceJndiName

flowable/flowable-engine · error · FlowableException

couldn't lookup datasource from

Error message

couldn't lookup datasource from

What it means

During engine configuration, if no DataSource was set directly, the engine tries to look one up from JNDI using the configured dataSourceJndiName. If the InitialContext lookup fails for any reason, this FlowableException wraps the underlying cause.

Source

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

     */
    protected VariableLengthVerifier variableLengthVerifier = NoopVariableLengthVerifier.INSTANCE;

    protected VariableValueConversionHandler variableValueConversionHandler;

    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);

View on GitHub (pinned to d6d39ce1c6)

Solutions

Verify the exact JNDI name exists in the container and matches dataSourceJndiName
Declare the datasource resource in the application server configuration (context.xml / server datasource)
Alternatively set the dataSource object directly or use jdbcUrl/jdbcDriver/jdbcUsername/jdbcPassword instead of JNDI

Example fix

// before
processEngineConfiguration.setDataSourceJndiName("java:/comp/env/jdbc/flowable");
// after
processEngineConfiguration.setDataSource(dataSource); // or use setJdbcUrl/setJdbcDriver/setJdbcUsername/setJdbcPassword

Defensive patterns

Strategy: validation

Validate before calling

if (config.getDataSource() == null && config.getDataSourceJndiName() != null) { try { new InitialContext().lookup(config.getDataSourceJndiName()); } catch (NamingException e) { throw new IllegalStateException("JNDI datasource not found: " + config.getDataSourceJndiName(), e); } }

Try / catch

try { engine = cfg.buildProcessEngine(); } catch (FlowableException e) { if (e.getMessage().startsWith("couldn't lookup datasource")) { /* fall back to direct DataSource */ } throw e; }

Prevention

Verify JNDI binding exists in the target environment before deployment
Prefer injecting a DataSource directly (Spring/boot) over JNDI lookup
Use the same JNDI name constants in config and container descriptor

When it happens

Trigger: AbstractEngineConfiguration.initDataSource() with dataSource == null and dataSourceJndiName != null, where InitialContext().lookup(jndiName) throws (name not bound, no JNDI provider, wrong name, naming exception).

Common situations: Deploying outside an app server (no JNDI), typo in the JNDI name, datasource not declared in the container (e.g. missing resource definition in Tomcat/WildFly), missing jee jar on classpath in Spring Boot.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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