{"record":{"id":"2c338144a491167c","repo":"flowable/flowable-engine","slug":"version-mismatch-library-version-is-enginevers","errorCode":null,"errorMessage":"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","messagePattern":"version mismatch: library version is '(.+?)', db version is (.+?) 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","errorType":"exception","errorClass":"FlowableWrongDbException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/db/EngineSqlScriptBasedDbSchemaManager.java","lineNumber":100,"sourceCode":"    public void schemaCreate() {\n\n        if (lockConfiguration.isUseLockForDatabaseSchemaUpdate()) {\n            LockManager lockManager = lockConfiguration.getLockManager(getDbSchemaLockName());\n            lockManager.waitForLockRunAndRelease(lockConfiguration.getSchemaLockWaitTime(), () -> {\n                schemaCreateInLock();\n                return null;\n            });\n        } else {\n            schemaCreateInLock();\n        }\n    }\n\n    protected void schemaCreateInLock() {\n        if (isEngineTablePresent()) {\n            String dbVersion = getDbVersion();\n            String engineVersion = getEngineVersion();\n            if (!engineVersion.equals(dbVersion)) {\n                throw new FlowableWrongDbException(engineVersion, dbVersion);\n            }\n        } else {\n            dbSchemaCreateEngine();\n        }\n    }\n\n    protected void dbSchemaCreateEngine() {\n        executeMandatorySchemaResource(\"create\", context);\n    }\n\n    @Override\n    public void schemaDrop() {\n\n        try {\n            executeMandatorySchemaResource(\"drop\", context);\n\n        } catch (Exception e) {\n            logger.info(\"Error dropping {} tables\", context, e);","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/db/EngineSqlScriptBasedDbSchemaManager.java#L82-L118","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set databaseSchemaUpdate=\"true\" once so the engine runs the upgrade scripts to bring the DB to the library version.","Manually execute the Flowable DB upgrade scripts (org/flowable/db/upgrade/<dbtype>/flowable_<old>_to_<new>) between versions.","Align all services sharing the database on the same Flowable version.","Restore the matching library version if the downgrade was unintentional."],"exampleFix":"// before: pinned new lib, schema old\n<property name=\"databaseSchemaUpdate\" value=\"false\"/>// after\n<property name=\"databaseSchemaUpdate\" value=\"true\"/> // let engine upgrade schema once","handlingStrategy":"try-catch","validationCode":"String db = jdbcQuery(\"SELECT VALUE_ FROM ACT_GE_PROPERTY WHERE NAME_='schema.version'\");\nif (!db.equals(flowableLibVersion)) runUpgradeScripts(db, flowableLibVersion);","typeGuard":null,"tryCatchPattern":"catch (FlowableWrongDbException e) { log.error(\"lib {} vs db {}\", e.getLibraryVersion(), e.getDbVersion()); /* run upgrade scripts or align versions */ throw e; }","preventionTips":["Always run the between-versions upgrade scripts when bumping Flowable.","Manage Flowable versions via a single BOM.","Never let differently-versioned engines share one database.","Set databaseSchemaUpdate=true temporarily for one controlled boot to upgrade."],"tags":["database","schema","version-mismatch","upgrade","flowable"],"backgroundTag":"schema-validation-failed","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"}