What causes "Invalid dbSqlSession: no active connection found" in flowable/flowable-engine?

Verify the datasource and transaction factory are correctly wired into the process/engine configuration.

flowable/flowable-engine · error · FlowableException

Invalid dbSqlSession: no active connection found

Error message

Invalid dbSqlSession: no active connection found

What it means

Session opening failure in the DbSqlSessionFactory: the newly created DbSqlSession has no active JDBC connection (connection retrieval produced none), so schema/catalog setup and SQL execution cannot proceed.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/db/DbSqlSessionFactory.java:99

    @Override
    public Session openSession(CommandContext commandContext) {
        DbSqlSession dbSqlSession = createDbSqlSession();
        if (getDatabaseSchema() != null && getDatabaseSchema().length() > 0) {
            try {
                dbSqlSession.getSqlSession().getConnection().setSchema(getDatabaseSchema());
            } catch (SQLException e) {
                throw new FlowableException("Could not set database schema on connection", e);
            }
        }
        if (getDatabaseCatalog() != null && getDatabaseCatalog().length() > 0) {
            try {
                dbSqlSession.getSqlSession().getConnection().setCatalog(getDatabaseCatalog());
            } catch (SQLException e) {
                throw new FlowableException("Could not set database catalog on connection", e);
            }
        }
        if (dbSqlSession.getSqlSession().getConnection() == null) {
            throw new FlowableException("Invalid dbSqlSession: no active connection found");
        }
        return dbSqlSession;
    }

    protected DbSqlSession createDbSqlSession() {
        return new DbSqlSession(this, Context.getCommandContext().getSession(EntityCache.class));
    }

    // insert, update and delete statements
    // /////////////////////////////////////

    public String getInsertStatement(Entity object) {
        return getStatement(object.getClass(), insertStatements, "insert");
    }

    public String getInsertStatement(Class<? extends Entity> clazz) {
        return getStatement(clazz, insertStatements, "insert");
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Verify the datasource and transaction factory are correctly wired into the process/engine configuration.
Ensure a transaction/connection is active for the command (correct command context interceptor setup).
Check pool settings so connections aren't closed/recycled mid-command.
Run with debug logging on transaction management to see when the connection is lost.

Example fix

// before
<property name="dataSource" ref="undefinedDataSource" />
// after
<bean id="dataSource" class="org.apache.commons.dbcp2.BasicDataSource">
  <property name="url" value="jdbc:h2:mem:flowable" />
  <property name="username" value="sa" />
</bean>

Defensive patterns

Strategy: validation

Validate before calling

try (Connection c = dataSource.getConnection()) {
  ResultSet rs = c.getMetaData().getCatalogs();
  boolean found = false;
  while (rs.next()) { if (catalog.equalsIgnoreCase(rs.getString("TABLE_CAT"))) found = true; }
  if (!found) throw new IllegalStateException("Catalog not found: " + catalog);
  c.setCatalog(catalog);
}

Try / catch

try { engineConfiguration.buildProcessEngine(); }
catch (FlowableException e) {
  if (e.getMessage().contains("set database catalog")) { /* verify catalog or encode it in the JDBC URL */ }
  throw e;
}

Prevention

Confirm the catalog/database exists before startup.
Encode the database in the JDBC URL instead of setCatalog when possible.
Keep JDBC drivers up to date.
Validate configuration values in a smoke test before deploying.

When it happens

Trigger: The MyBatis SqlSession/transaction has no active Connection — typically a misconfigured datasource/transaction factory, or connection retrieval returning null in a custom environment.

Common situations: Custom CommandContext/transaction interceptor that fails to attach the connection; misconfigured Spring/standalone datasource; connection closed by the pool before session use.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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