flowable/flowable-engine · critical · FlowableWrongDbException

Wrong db version: expected ${ProcessEngine.VERSION}, found $

Error message

Wrong db version: expected ${ProcessEngine.VERSION}, found ${dbVersion}

What it means

Thrown as FlowableWrongDbException during schemaCheckVersion when the version recorded in the Flowable database tables (ACT_GE_PROPERTY, schema.version) does not equal the running library's ProcessEngine.VERSION. The engine requires an exact match to guarantee schema compatibility.

Source

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

import org.flowable.common.engine.impl.db.DbSqlSession;
import org.flowable.common.engine.impl.persistence.entity.PropertyEntity;
import org.flowable.common.engine.impl.persistence.entity.PropertyEntityImpl;
import org.flowable.engine.ProcessEngine;
import org.flowable.engine.impl.cfg.ProcessEngineConfigurationImpl;
import org.flowable.engine.impl.util.CommandContextUtil;

public class ProcessDbSchemaManager extends AbstractSqlScriptBasedDbSchemaManager {
    
    protected static final Pattern CLEAN_VERSION_REGEX = Pattern.compile("\\d\\.\\d*");

    protected static final String PROCESS_DB_SCHEMA_LOCK_NAME = "processDbSchemaLock";
    
    @Override
    public void schemaCheckVersion() {
        try {
            String dbVersion = getDbVersion();
            if (!ProcessEngine.VERSION.equals(dbVersion)) {
                throw new FlowableWrongDbException(ProcessEngine.VERSION, dbVersion);
            }

            String errorMessage = null;
            if (!isEngineTablePresent()) {
                errorMessage = addMissingComponent(errorMessage, "engine");
            }
            if (CommandContextUtil.getDbSqlSession().getDbSqlSessionFactory().isDbHistoryUsed() && !isHistoryTablePresent()) {
                errorMessage = addMissingComponent(errorMessage, "history");
            }

            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 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",

View on GitHub (pinned to d6d39ce1c6)

Solutions

Run the Flowable DB upgrade scripts (upgrade/flowable.*.upgrade.*.sql) matching your old-to-new version path, or set databaseSchemaUpdate=true to let the engine upgrade the schema.
Align the Flowable dependency version with the version that created the database, or upgrade both together.
Never set databaseSchemaUpdate=false on a version-mismatched DB in production; use 'validate' plus scripted migrations instead.

Example fix

// before
<property name="databaseSchemaUpdate" value="false"/> <!-- DB has old schema version -->
// after
<property name="databaseSchemaUpdate" value="true"/> <!-- or apply SQL upgrade scripts first, then set back to false -->

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try { engine = cfg.buildProcessEngine(); } catch (FlowableWrongDbException e) { LOG.error("library {} vs db {}", e.getLibraryVersion(), e.getDbVersion()); }

Prevention

Version-lock the Flowable library and apply matching SQL upgrade scripts on every bump
Use databaseSchemaUpdate='validate' in production to fail fast with a clear version report
Never mix Flowable versions across apps sharing one database

When it happens

Trigger: Engine started with databaseSchemaUpdate=false (or 'validate') against a DB created by a different Flowable/Activiti engine version; upgrading the Flowable jar without running the schema upgrade; downgrading the jar below the DB schema version.

Common situations: Deploying a new application version with a newer Flowable dependency while pointing at the old database; copying the library into an app that uses an old shared database; running the engine before schema upgrade scripts were applied.

Related errors

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