{"record":{"id":"a8c125f59d884812","repo":"flowable/flowable-engine","slug":"version-mismatch-library-version-is-libraryver","errorCode":null,"errorMessage":"version mismatch: library version is '${libraryVersion}', 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":"critical","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/db/ProcessDbSchemaManager.java","lineNumber":105,"sourceCode":"    public void schemaCreate() {\n        \n        ProcessEngineConfigurationImpl processEngineConfiguration = getProcessEngineConfiguration();\n        if (processEngineConfiguration.isUseLockForDatabaseSchemaUpdate()) {\n            LockManager lockManager = processEngineConfiguration.getManagementService().getLockManager(PROCESS_DB_SCHEMA_LOCK_NAME);\n            lockManager.waitForLockRunAndRelease(processEngineConfiguration.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            if (!ProcessEngine.VERSION.equals(dbVersion)) {\n                throw new FlowableWrongDbException(ProcessEngine.VERSION, dbVersion);\n            }\n        } else {\n            dbSchemaCreateEngine();\n        }\n        \n        if (CommandContextUtil.getDbSqlSession().getDbSqlSessionFactory().isDbHistoryUsed()) {\n            dbSchemaCreateHistory();\n        }\n    }\n\n    protected void dbSchemaCreateHistory() {\n        executeMandatorySchemaResource(\"create\", \"history\");\n    }\n\n    protected void dbSchemaCreateEngine() {\n        executeMandatorySchemaResource(\"create\", \"engine\");\n    }\n","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/db/ProcessDbSchemaManager.java#L87-L123","documentation":"Thrown as FlowableWrongDbException inside schemaCreateInLock when engine tables already exist but their recorded schema version differs from the running library's version. Even in 'create' mode, the engine will not silently run against a mismatched schema; it demands an explicit upgrade.","triggerScenarios":"databaseSchemaUpdate=true (schemaCreate path) against a database whose engine tables were created by a different Flowable/Activiti version; upgrading the Flowable jar while reusing the old DB; concurrent engines of different versions sharing one DB.","commonSituations":"Application dependency bump deployed against the existing production schema; two applications on different Flowable versions sharing a database; skipping intermediate upgrade scripts during a multi-version jump.","solutions":["Apply the official SQL upgrade scripts covering each intermediate version between the DB version and the library version, then restart.","Let databaseSchemaUpdate=true handle the upgrade only for supported paths, or use the Flowable upgrade tooling for large jumps.","Ensure all applications sharing the database use the same Flowable version to prevent repeated mismatch conflicts."],"exampleFix":"// before\n<property name=\"databaseSchemaUpdate\" value=\"true\"/> <!-- DB at older schema version -->\n// after\n<!-- run upgrade/flowable.mysql.upgrade.from.5.x.to.6.x.sql first, then -->\n<property name=\"databaseSchemaUpdate\" value=\"false\"/>","handlingStrategy":"try-catch","validationCode":"String dbVer = managementService.getProperties().get(\"schema.version\"); if (dbVer != null && !ProcessEngine.VERSION.equals(dbVer)) { runUpgradeScripts(dbVer, ProcessEngine.VERSION); }","typeGuard":null,"tryCatchPattern":"try { engine = cfg.buildProcessEngine(); } catch (FlowableWrongDbException e) { LOG.error(\"expected {} found {}\", e.getLibraryVersion(), e.getDbVersion()); throw e; }","preventionTips":["Apply chained upgrade scripts for every intermediate version when jumping releases","Keep all apps sharing the database on the same Flowable version","Snapshot/backup the schema before any Flowable upgrade"],"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"}