What causes "Could not set database schema on connection" in flowable/flowable-engine?

Verify the schema exists and the DB user has rights: CREATE SCHEMA / GRANT as needed.

flowable/flowable-engine · error · FlowableException

Could not set database schema on connection

Error message

Could not set database schema on connection

What it means

Thrown by DbSqlSessionFactory.openSession when applying the configured database schema to the underlying JDBC connection fails with SQLException; the connection cannot be put into the expected schema, so the persistence session is not usable.

Source

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

    protected boolean usePrefixId;
    
    public DbSqlSessionFactory(boolean usePrefixId) {
        this.usePrefixId = usePrefixId;
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

Verify the schema exists and the DB user has rights: CREATE SCHEMA / GRANT as needed.
Check the schema name spelling and case for your database.
If the driver doesn't support setSchema, prepend the schema to the JDBC URL or leave databaseSchema unset and use fully qualified table prefixes.
Use a current JDBC driver version compatible with your database.

Example fix

// before
<property name="databaseSchema" value="FLOWABLE" /> // schema missing or unsupported
// after
-- run first on the DB
CREATE SCHEMA FLOWABLE AUTHORIZATION app_user;

Defensive patterns

Strategy: try-catch

Validate before calling

long cnt = taskService.createTaskQuery().taskId(id).count();
if (cnt == 0) return; // nothing to delete
Task fresh = taskService.createTaskQuery().taskId(id).singleResult(); // freshest revision

Try / catch

try { /* delete entity */ }
catch (FlowableOptimisticLockingException e) {
  // row already deleted or changed: verify state and continue idempotently
}

Prevention

Make deletes idempotent: treat zero-row delete as success when appropriate.
Serialize concurrent deletes of the same row (locking or single-writer paths).
Avoid holding entities across user think-time; reload before deleting.
For async jobs, rely on Flowable's optimistic-locking retry for jobs.

When it happens

Trigger: databaseSchema (engine configuration) is set and the underlying connection's setSchema call throws — e.g. driver does not support setSchema, schema does not exist, or the DB user lacks permission to use it.

Common situations: Schema name typo or wrong case (Oracle/H2 case sensitivity); schema not created before engine start; drivers with no-op/throwing setSchema implementations; connecting to a database where the user's default schema differs.

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

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