flowable/flowable-engine · error · FlowableException

Could not set database catalog on connection

Error message

Could not set database catalog on connection

What it means

Thrown by DbSqlSessionFactory.openSession when applying the configured database catalog to the JDBC connection fails with SQLException; session setup is aborted because queries would target the wrong catalog.

Source

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

    public Class<?> getSessionType() {
        return DbSqlSession.class;
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Confirm the catalog/database exists and the user can connect to it.
2. Check the databaseCatalog value spelling/case.
3. Alternatively encode the catalog in the JDBC URL and remove the databaseCatalog property.
4. Upgrade the JDBC driver to a version supporting setCatalog for your DBMS.

Example fix

// before
<property name="databaseCatalog" value="flowable_db" /> // db renamed
// after
<property name="databaseCatalog" value="flowable_prod" />

try (Connection c = dataSource.getConnection()) {
  DatabaseMetaData md = c.getMetaData();
  try (ResultSet rs = md.getSchemas()) {
    boolean found = false;
    while (rs.next()) { if (schema.equalsIgnoreCase(rs.getString("TABLE_SCHEM"))) found = true; }
    if (!found) throw new IllegalStateException("Schema not found: " + schema);
  }
  c.setSchema(schema); // fail fast outside engine startup
}

try { engineConfiguration.buildProcessEngine(); }
catch (FlowableException e) {
  if (e.getMessage().contains("set database schema")) { /* check schema existence/permissions or unset databaseSchema */ }
  throw e;
}

When it happens

Trigger: databaseCatalog is configured and connection.setCatalog throws — catalog (database name) does not exist, user lacks access, or driver rejects the call.

Common situations: MySQL/SQL Server catalog typo; catalog dropped or renamed; permissions changed; driver incompatibility with setCatalog.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Could not set database schema on connection
• Invalid dbSqlSession: no active connection found
• DataSource or JDBC properties have to be specified in a proc
• version mismatch: library version is '${currentVersion}', db
• Flowable database problem: ${errorMessage}

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