flowable/flowable-engine · error · FlowableException

couldn't get ${context} 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.

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)

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
}

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

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

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

• Failed to get change log version from ${changeLogTableName}
• couldn't ${operation} db schema: ${exceptionSqlStatement}
• No flowable tables in DB. Set property "databaseSchemaUpdate
• version mismatch: library version is '${engineVersion}', db
• version mismatch: library version is '${FlowableVersions.CUR

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