{"record":{"id":"69acaf7973227b16","repo":"flowable/flowable-engine","slug":"wrong-db-version-expected-processengine-version","errorCode":null,"errorMessage":"Wrong db version: expected ${ProcessEngine.VERSION}, found ${dbVersion}","messagePattern":"Wrong db version: expected (.+?), found (.+?)","errorType":"exception","errorClass":"FlowableWrongDbException","httpStatus":null,"severity":"critical","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/db/ProcessDbSchemaManager.java","lineNumber":41,"sourceCode":"import org.flowable.common.engine.impl.db.DbSqlSession;\nimport org.flowable.common.engine.impl.persistence.entity.PropertyEntity;\nimport org.flowable.common.engine.impl.persistence.entity.PropertyEntityImpl;\nimport org.flowable.engine.ProcessEngine;\nimport org.flowable.engine.impl.cfg.ProcessEngineConfigurationImpl;\nimport org.flowable.engine.impl.util.CommandContextUtil;\n\npublic class ProcessDbSchemaManager extends AbstractSqlScriptBasedDbSchemaManager {\n    \n    protected static final Pattern CLEAN_VERSION_REGEX = Pattern.compile(\"\\\\d\\\\.\\\\d*\");\n\n    protected static final String PROCESS_DB_SCHEMA_LOCK_NAME = \"processDbSchemaLock\";\n    \n    @Override\n    public void schemaCheckVersion() {\n        try {\n            String dbVersion = getDbVersion();\n            if (!ProcessEngine.VERSION.equals(dbVersion)) {\n                throw new FlowableWrongDbException(ProcessEngine.VERSION, dbVersion);\n            }\n\n            String errorMessage = null;\n            if (!isEngineTablePresent()) {\n                errorMessage = addMissingComponent(errorMessage, \"engine\");\n            }\n            if (CommandContextUtil.getDbSqlSession().getDbSqlSessionFactory().isDbHistoryUsed() && !isHistoryTablePresent()) {\n                errorMessage = addMissingComponent(errorMessage, \"history\");\n            }\n\n            if (errorMessage != null) {\n                throw new FlowableException(\"Flowable database problem: \" + errorMessage);\n            }\n\n        } catch (Exception e) {\n            if (isMissingTablesException(e)) {\n                throw new FlowableException(\n                        \"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\",","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/db/ProcessDbSchemaManager.java#L23-L59","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n<property name=\"databaseSchemaUpdate\" value=\"false\"/> <!-- DB has old schema version -->\n// after\n<property name=\"databaseSchemaUpdate\" value=\"true\"/> <!-- or apply SQL upgrade scripts first, then set back to false -->","handlingStrategy":"validation","validationCode":"String dbVer = managementService.getProperties().get(\"schema.version\"); if (!ProcessEngine.VERSION.equals(dbVer)) { runUpgradeScripts(dbVer, ProcessEngine.VERSION); }","typeGuard":null,"tryCatchPattern":"try { engine = cfg.buildProcessEngine(); } catch (FlowableWrongDbException e) { LOG.error(\"library {} vs db {}\", e.getLibraryVersion(), e.getDbVersion()); }","preventionTips":["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"],"tags":["database","schema-version","upgrade"],"backgroundTag":"schema-version-incompatible","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}