flowable/flowable-engine · error · FlowableWrongDbException

version mismatch: library version is '${FlowableVersions.CUR

Error message

version mismatch: library version is '${FlowableVersions.CURRENT_VERSION}', 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 from ServiceSqlScriptBasedDbSchemaManager.schemaCreate (reached via schemaUpdate): the service-engine tables exist but the version recorded in the schema (getSchemaVersion()) differs from FlowableVersions.CURRENT_VERSION. Flowable service modules (e.g. event registry, service registry, idm) enforce exact schema/library version parity.

Source

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

 */
public abstract class ServiceSqlScriptBasedDbSchemaManager extends AbstractSqlScriptBasedDbSchemaManager {
    
    protected String table;
    protected String schemaComponent;
    protected String schemaVersionProperty;
    
    public ServiceSqlScriptBasedDbSchemaManager(String table, String schemaComponent, String schemaVersionProperty) {
        this.table = table;
        this.schemaComponent = schemaComponent;
        this.schemaVersionProperty = schemaVersionProperty;
    }
    
    @Override
    public void schemaCreate() {
        if (isUpdateNeeded()) {
            String dbVersion = getSchemaVersion();
            if (!FlowableVersions.CURRENT_VERSION.equals(dbVersion)) {
                throw new FlowableWrongDbException(FlowableVersions.CURRENT_VERSION, dbVersion);
            }
        } else {
            internalDbSchemaCreate();
        }
    }

    protected void internalDbSchemaCreate() {
        executeMandatorySchemaResource("create", schemaComponent);
    }

    @Override
    public void schemaDrop() {
        try {
            executeMandatorySchemaResource("drop", schemaComponent);
        } catch (Exception e) {
            logger.info("Error dropping {} tables", schemaComponent, e);
        }
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Run the module's upgrade SQL scripts to bring its schema to the current version, or set databaseSchemaUpdate="true" once to auto-upgrade.
Align all Flowable module dependencies in your build to the same version (e.g. via flowable-root/BOM).
If a rollback caused it, redeploy the matching library version or downgrade the schema with the appropriate scripts.
Verify with SELECT on the module's version/property table which version the DB actually holds.

Example fix

// before: mixed versions
<dependency><artifactId>flowable-engine</artifactId><version>7.0.0</version></dependency>
<dependency><artifactId>flowable-event-registry</artifactId><version>6.8.0</version></dependency>
// after: align via BOM
<dependencyManagement><dependency><groupId>org.flowable</groupId><artifactId>flowable-bom</artifactId><version>7.0.0</version><type>pom</type><scope>import</scope></dependency></dependencyManagement>

Defensive patterns

Strategy: validation

Validate before calling

String dbVer = jdbcQuery("SELECT VERSION_ FROM FLW_EV_DATABASECHANGELOGLOCK") /* module property table */;
if (!dbVer.equals(flowableVersion)) runUpgradeScripts();

Try / catch

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

Prevention

Import flowable-bom to keep all module versions identical.
Run each module's upgrade scripts on every Flowable upgrade.
Never share one DB across differently-versioned deployments.
Set databaseSchemaUpdate=true for one controlled upgrade boot.

When it happens

Trigger: Booting a service engine module when its tables were created by a different Flowable release: dependency upgraded without running the module's upgrade scripts, mixed module versions (one module newer than others), or DB shared between deployments of different versions.

Common situations: Partial upgrade — core engine upgraded but service module schema left old; multiple microservices sharing one DB with different Flowable versions; reverting a release without downgrading the schema.

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

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