flowable/flowable-engine · critical · FlowableWrongDbException

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

Error message

version mismatch: library version is '${libraryVersion}', 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

Thrown as FlowableWrongDbException inside schemaCreateInLock when engine tables already exist but their recorded schema version differs from the running library's version. Even in 'create' mode, the engine will not silently run against a mismatched schema; it demands an explicit upgrade.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/db/ProcessDbSchemaManager.java:105

    public void schemaCreate() {
        
        ProcessEngineConfigurationImpl processEngineConfiguration = getProcessEngineConfiguration();
        if (processEngineConfiguration.isUseLockForDatabaseSchemaUpdate()) {
            LockManager lockManager = processEngineConfiguration.getManagementService().getLockManager(PROCESS_DB_SCHEMA_LOCK_NAME);
            lockManager.waitForLockRunAndRelease(processEngineConfiguration.getSchemaLockWaitTime(), () -> {
                schemaCreateInLock();
                return null;
            });
        } else {
            schemaCreateInLock();
        }
    }

    protected void schemaCreateInLock() {
        if (isEngineTablePresent()) {
            String dbVersion = getDbVersion();
            if (!ProcessEngine.VERSION.equals(dbVersion)) {
                throw new FlowableWrongDbException(ProcessEngine.VERSION, dbVersion);
            }
        } else {
            dbSchemaCreateEngine();
        }
        
        if (CommandContextUtil.getDbSqlSession().getDbSqlSessionFactory().isDbHistoryUsed()) {
            dbSchemaCreateHistory();
        }
    }

    protected void dbSchemaCreateHistory() {
        executeMandatorySchemaResource("create", "history");
    }

    protected void dbSchemaCreateEngine() {
        executeMandatorySchemaResource("create", "engine");
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Apply the official SQL upgrade scripts covering each intermediate version between the DB version and the library version, then restart.
Let databaseSchemaUpdate=true handle the upgrade only for supported paths, or use the Flowable upgrade tooling for large jumps.
Ensure all applications sharing the database use the same Flowable version to prevent repeated mismatch conflicts.

Example fix

// before
<property name="databaseSchemaUpdate" value="true"/> <!-- DB at older schema version -->
// after
<!-- run upgrade/flowable.mysql.upgrade.from.5.x.to.6.x.sql first, then -->
<property name="databaseSchemaUpdate" value="false"/>

Defensive patterns

Strategy: try-catch

Validate before calling

String dbVer = managementService.getProperties().get("schema.version"); if (dbVer != null && !ProcessEngine.VERSION.equals(dbVer)) { runUpgradeScripts(dbVer, ProcessEngine.VERSION); }

Try / catch

try { engine = cfg.buildProcessEngine(); } catch (FlowableWrongDbException e) { LOG.error("expected {} found {}", e.getLibraryVersion(), e.getDbVersion()); throw e; }

Prevention

Apply chained upgrade scripts for every intermediate version when jumping releases
Keep all apps sharing the database on the same Flowable version
Snapshot/backup the schema before any Flowable upgrade

When it happens

Trigger: databaseSchemaUpdate=true (schemaCreate path) against a database whose engine tables were created by a different Flowable/Activiti version; upgrading the Flowable jar while reusing the old DB; concurrent engines of different versions sharing one DB.

Common situations: Application dependency bump deployed against the existing production schema; two applications on different Flowable versions sharing a database; skipping intermediate upgrade scripts during a multi-version jump.

Related errors

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