flowable/flowable-engine · error · FlowableWrongDbException

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

Error message

version mismatch: library version is '${engineVersion}', 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 (surfaced via schemaCreateInLock) raised when the engine tables exist but the version stored in the database differs from the version of the Flowable library on the classpath. Flowable requires the DB schema version to exactly match the engine version before starting.

Source

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

    public void schemaCreate() {

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

    protected void schemaCreateInLock() {
        if (isEngineTablePresent()) {
            String dbVersion = getDbVersion();
            String engineVersion = getEngineVersion();
            if (!engineVersion.equals(dbVersion)) {
                throw new FlowableWrongDbException(engineVersion, dbVersion);
            }
        } else {
            dbSchemaCreateEngine();
        }
    }

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

    @Override
    public void schemaDrop() {

        try {
            executeMandatorySchemaResource("drop", context);

        } catch (Exception e) {
            logger.info("Error dropping {} tables", context, e);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set databaseSchemaUpdate="true" once so the engine runs the upgrade scripts to bring the DB to the library version.
2. Manually execute the Flowable DB upgrade scripts (org/flowable/db/upgrade/<dbtype>/flowable_<old>_to_<new>) between versions.
3. Align all services sharing the database on the same Flowable version.
4. Restore the matching library version if the downgrade was unintentional.

Example fix

// before: pinned new lib, schema old
<property name="databaseSchemaUpdate" value="false"/>// after
<property name="databaseSchemaUpdate" value="true"/> // let engine upgrade schema once

String db = jdbcQuery("SELECT VALUE_ FROM ACT_GE_PROPERTY WHERE NAME_='schema.version'");
if (!db.equals(flowableLibVersion)) runUpgradeScripts(db, flowableLibVersion);

catch (FlowableWrongDbException e) { log.error("lib {} vs db {}", e.getLibraryVersion(), e.getDbVersion()); /* run upgrade scripts or align versions */ throw e; }

When it happens

Trigger: Booting an engine with databaseSchemaUpdate="false" (or "check-version" semantics) after the library was upgraded or downgraded: getEngineVersion() != getDbVersion(). schemaCreateInLock is reached via schemaCreate when tables are already present.

Common situations: Upgrading the Flowable Maven dependency without running the DB upgrade scripts; rolling back a release against a newer schema; multiple engine versions sharing one database; create-drop omitted in tests where schema was built by a different version.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• version mismatch: library version is '${FlowableVersions.CUR
• Could not update Flowable database schema: unknown version f
• No flowable tables in DB. Set property "databaseSchemaUpdate
• couldn't get ${context} db schema version
• Failed to get change log version from ${changeLogTableName}

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