flowable/flowable-engine · critical · FlowableWrongDbException

version mismatch: library version is '${currentVersion}', db

Error message

version mismatch: library version is '${currentVersion}', db version is ${dbVersion} Hint: Set <property name="databaseSchemaUpdate" to value="true" or value="create-drop" (use create-drop for testing only!) in bean processEngineConfiguration in flowable.cfg.xml for automatic schema creation

What it means

FlowableWrongDbException: the engine library version does not equal the version recorded in the ACT_GE_PROPERTY table. The database schema was built with a different Flowable version than the code is running.

Source

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

    protected abstract String getEngineVersion();

    protected abstract String getSchemaVersionPropertyName();

    protected abstract String getDbSchemaLockName();

    protected abstract String getEngineTableName();

    protected abstract String getChangeLogTableName();

    protected abstract String getDbVersionForChangelogVersion(String changeLogVersion);

    @Override
    public void schemaCheckVersion() {
        try {
            String dbVersion = getDbVersion();
            String currentVersion = getEngineVersion();
            if (!currentVersion.equals(dbVersion)) {
                throw new FlowableWrongDbException(currentVersion, dbVersion);
            }

            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) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

Run the database upgrade scripts from the Flowable distribution matching the target version (dbupgrade scripts in order).
Set databaseSchemaUpdate=true (or "create-drop" for tests) to let the engine update the schema automatically.
Align dependency versions: ensure all flowable-* modules are the same version as the intended schema.
Point the engine at the correct database if this one belongs to another Flowable version.

Example fix

// before
<property name="databaseSchemaUpdate" value="false" /> // jars upgraded, DB still on old version
// after
<property name="databaseSchemaUpdate" value="true" /> // or run sql/upgrade scripts for your version

Defensive patterns

Strategy: validation

Validate before calling

try (Connection c = dataSource.getConnection()) {
  if (c == null || c.isClosed()) throw new IllegalStateException("DataSource returned invalid connection");
}

Try / catch

try { engineConfiguration.buildProcessEngine(); }
catch (FlowableException e) {
  if (e.getMessage().contains("no active connection found")) { /* fix datasource/transaction wiring */ }
  throw e;
}

Prevention

Verify datasource bean wiring and pool health before building the engine.
Do not replace Flowable's transaction factory/interceptors without keeping connection attachment intact.
Monitor pool exhaustion and connection timeouts.
Smoke-test engine startup against the real datasource in CI.

When it happens

Trigger: Engine startup (or schemaCheckVersion) with databaseSchemaUpdate=false when the DB's schema.version property differs from the running Flowable version — e.g. after upgrading the flowable jars without upgrading the schema, or pointing a new engine at an old database.

Common situations: Upgraded maven dependency but not run the upgrade scripts; downgraded jars against a newer schema; multiple engine versions sharing one database; copied production DB into dev with different jar versions.

Related errors

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