flowable/flowable-engine · error · FlowableException

couldn't get db schema version

Error message

couldn't get ${context} db schema version

What it means

Generic wrap-around thrown in schemaCheckVersion: a non-missing-tables exception occurred while reading the DB schema version for the given context (e.g. 'process engine', 'identity', 'cmmn'). The original exception is preserved as the cause; the message just reports Flowable could not determine the installed schema version.

Solutions

  1. Inspect the wrapped cause (e.getCause()) for the real SQL error and fix that first.
  2. Verify the version/property table exists and contains the schema.version/schema.history rows (recreate schema or run upgrade scripts).
  3. Test DB connectivity and credentials with a plain JDBC query before engine startup.
  4. Confirm the database and driver are supported by your Flowable version; run the official upgrade SQL scripts after upgrading.

Example fix

// diagnose
try {
  engineConfig.buildProcessEngine();
} catch (FlowableException e) {
  e.getCause().printStackTrace(); // real SQL problem
}
Defensive patterns

Strategy: try-catch

Validate before calling

try (Statement s = c.createStatement()) { ResultSet rs = s.executeQuery("SELECT VALUE_ FROM ACT_GE_PROPERTY WHERE NAME_='schema.version'"); }

Try / catch

catch (FlowableException e) { log.error("schema version lookup failed; cause:", e.getCause()); throw e; }

Prevention

When it happens

Trigger: schemaCheckVersion queries the version table (e.g. SELECT VALUE_ FROM ACT_GE_PROPERTY WHERE NAME_='schema.version') and any unexpected exception other than a missing-tables error occurs: SQL syntax errors, corrupted/renamed property table, connection drops mid-query, driver incompatibility, table present but unreadable.

Common situations: Partially created or manually altered schema (ACT_GE_PROPERTY dropped or rows deleted); database outage or network failure during engine boot; using a Flowable version with a DB not on the supported list; permissions revoked on the property table.

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/8f9c9c8a97c7539c. Report an issue: GitHub.

Appendix: source

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

            String errorMessage = null;
            if (!isEngineTablePresent()) {
                errorMessage = addMissingComponent(errorMessage, context);
            }

            if (errorMessage != null) {
                throw new FlowableException("Flowable database problem: " + errorMessage);
            }

        } catch (Exception e) {
            if (isMissingTablesException(e)) {
                throw new FlowableException(
                        "No flowable tables in DB. Set property \"databaseSchemaUpdate\" \"true\" or value=\"create-drop\" (use create-drop for testing only!) for automatic schema creation",
                        e);
            } else {
                if (e instanceof RuntimeException) {
                    throw (RuntimeException) e;
                } else {
                    throw new FlowableException("couldn't get " + context + " db schema version", e);
                }
            }
        }

        logger.debug("flowable {} db schema check successful", context);
    }

    @Override
    public void schemaCreate() {

        if (lockConfiguration.isUseLockForDatabaseSchemaUpdate()) {
            LockManager lockManager = lockConfiguration.getLockManager(getDbSchemaLockName());
            lockManager.waitForLockRunAndRelease(lockConfiguration.getSchemaLockWaitTime(), () -> {
                schemaCreateInLock();
                return null;
            });
        } else {
            schemaCreateInLock();

View on GitHub (pinned to d6d39ce1c6)